Is-Servent MCP: Għodod, Riżultati, u Dispjegament
F'din il-paġna
Lezzjon miktub mill-ġdid fit-3 ta’ Novembru 2026 abbażi tal-paġna Build an MCP server mid-dokumentazzjoni tal-Plugins ta’ OpenAI u l-kodiċi tal-MCP TypeScript SDK (1.32.2). Il-lezzjoni preċedenti kienet tiddeskrivi “azzjonijiet” (
defineAction,ActionError) minn SDK li ma jeżistix; dan ir-rwol issa huwa tal-għodod MCP. Sorsi: Build an MCP server · MCP TypeScript SDK.
Is-servent, l-identità tiegħu, u l-istruzzjonijiet tiegħu
Oħloq servent MCP b’isem u verżjoni stabbli. Matul l-inizjalizzazzjoni, jista’ jirritorna wkoll kamp instructions li ChatGPT u Codex jaqraw flimkien mal-metadejta tal-għodda. Irriżerva dan il-kamp għal linji gwida li japplikaw għall-għodod kollha—bħal ordni obbligatorja ta’ sejħiet jew limitu ta’ rata kondiviż—u żomm il-kontenut ewlieni fi ħdan l-ewwel 512 karattru. Tikkupjax u twaħħalx deskrizzjonijiet tal-għodod hawnhekk, u tippruvax tibdel il-personalità tal-mudell.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Before modifying a project, call get_project to confirm its ID and status.",
}
);
Għodda waħda għal kull azzjoni
Oħloq għodda waħda għal kull azzjoni distinta: list_projects, get_project, update_project, minflok għodda waħda ġenerali b’numru kbir ta’ modalitajiet. Kull għodda tgħaqqad isem orjentat lejn l-azzjoni, titlu li jinqara faċilment, deskrizzjoni li tispjega meta tużaha, skema ta’ input espliċita, skema ta’ output jekk tirritorna dejta strutturata, annotazzjonijiet preċiżi, u handle li jawtorizza it-talba qabel ma jaġixxi. Il-mudell jiddependi fuq din il-metadejta biex jiddeċiedi jekk u kif iċempel l-għodda—trattaha bħala parti mill-esperjenza tal-utent.
import { z } from "zod";
const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });
server.registerTool(
"get_project",
{
title: "View a project",
description:
"Use when the user wants details about a specific project in their Acme workspace. " +
"Requires the ID returned by list_projects.",
inputSchema: { id: z.string().min(1) },
outputSchema: { project: project },
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async ({ id }, extra) => {
const user = await authenticate(extra); // Your access control (Lesson 8)
const found = await loadProject(user, id); // Your data access
if (!found) {
return {
isError: true,
content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
};
}
return {
structuredContent: { project: found },
content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
};
}
);
authenticate u loadProject huma l-funzjonijiet tiegħek stess. Il-punt kritiku huwa l-pożizzjoni tagħhom: l-awtorizzazzjoni sseħħ fuq is-servent, ma’ kull talba. Qatt ma tiddependi fuq il-mudell biex tiddeċiedi jekk utent għandux permess biex jaċċessa dejta.
Riżultati utli mingħajr interfaċċja
Riżultat ta’ għodda jista’ jġorr tliet affarijiet:
structuredContent: dejta konċiża li l-mudell jista’ jispezzjona u jerġa’ juża f’sejħiet sussegwenti;content: test jew kontenut MCP ieħor li jgħinu jwieġeb;_meta: dejta maħsuba għall-klijent, moħbija mill-mudell.
Irritorna biżżejjed informazzjoni biex il-mudell ilesti x-xogħol mingħajr komponent viżiv, billi tuża IDs stabbli li għodod sussegwenti jistgħu jerġgħu jużaw. Żewġ imġibiet tal-SDK huma ta’ min jinnotahom. Għodda li tiddikjara outputSchema trid tirritorna structuredContent konformi fir-riżultati ta’ suċċess kollha; inkella, l-SDK iġib żball ta’ validazzjoni. Żball tan-negozju—bħal proġett nieqes jew azzjoni miċħuda—jiġi sinjalat b’riżultat b’isError: true akkumpanjat minn test spjegattiv li l-mudell jista’ jgħaddi lill-utent; dan it-tip ta’ riżultat jaqbeż il-validazzjoni tal-iskema tal-output.
Qatt ma tinkludi sigrieti, tokens tal-aċċess, jew dejta personali mhux meħtieġa f’riżultat, u ttrattax _meta bħala post sigur biex taħbi: dan il-kamp huwa moħbi mill-mudell, iżda mhuwiex protett.
Annotazzjonijiet u elicitazzjoni
L-annotazzjonijiet iridu jirriflettu l-imġiba attwali tal-għodda: issettja readOnlyHint għal true biss jekk ma tista’ timmodifika xejn, destructiveHint għal true jekk tista’ tikkawża effett irreversibbli jew diffiċli biex tħassar, u openWorldHint għal true jekk tmiss l-internet pubbliku jew entitajiet esterni miftuħa. Dawn jgħinu lil ChatGPT u Codex jagħżlu l-imġiba ta’ konferma t-tajba; huma ma jissostitwixxux il-loġika ta’ awtorizzazzjoni, validazzjoni, jew konferma fuq is-servent tiegħek.
Meta s-servent ikollu bżonn informazzjoni strutturata nieqsa mis-sejħa—bħal data jew għażla bejn żewġ għażliet—jista’ jitlobha permezz tal-elicitazzjoni, mekkaniżmu tal-protokoll MCP. Illimita dan għal dak li l-utent jista’ raġonevolment jipprovdi; qatt ma tużah biex tiġbor sigrieti jew biex tevita l-awtentikazzjoni normali.
Kontijiet multipli u għarfien tal-kumpanija
Żewġ kompatibbiltajiet opzjonali jtejbu l-integrazzjoni. Biex tgħin lill-utenti jgħaqqdu kontijiet multipli, esponi għodda tal-profil li hija awtentikata, ta’ qari biss, u mmarkata _meta["openai/profile"]: true. OpenAI tuża dan biex tidentifika l-kontijiet konnessi u tgħin lill-utenti jiddistingwu bejniethom. Il-profil huwa derivat mill-kredenzjali validati tat-talba, u kull sejħa tibqa’ limitata għal dawk il-kredenzjali.
Il-karatteristika company knowledge ta’ ChatGPT tista’ tuża l-għodod ta’ qari biss tas-servent tiegħek. Biex tagħmel plugin eliġibbli bħala sors, implimenta l-iskemi standard tal-input għall-għodod search u fetch, immarka għodod oħra ta’ qari biss b’readOnlyHint: true, u rritorna URLs assoluti li l-utent jista’ jiftaħ għas-sorsi li l-mudell irid jikkwota.
Dispjegament tal-endpoint
Is-sottomissjoni pubblika teħtieġ servent f’indirizz HTTPS stabbli u aċċessibbli pubblikament. Dan l-endpoint irid jappoġġja t-trasport streamable HTTP, jirrispondi f’URL stabbli (tipikament jispiċċa b’/mcp’), jissodisfa r-rekwiżiti ta’ latenza u disponibbiltà tal-flussi tax-xogħol tiegħek, jilħaq is-servizzi u d-dejta tiegħek, iżomm il-fruntieri tal-awtentikazzjoni u l-awtorizzazzjoni, u jipproduċi logs u metriċi għall-inizjalizzazzjoni u għall-fallimenti tas-sejħiet tal-għodod.
Is-Secure MCP Tunnel ta’ OpenAI jippermettilek tgħaqqad servent privat ma’ ChatGPT, iżda ma jissodisfax ir-rekwiżiti tas-sottomissjoni pubblika, lanqas tunnel temporanju jew indirizz lokali. Jekk is-servent irid jibqa’ privat, poġġi proxy HTTPS pubbliku quddiemu: mTLS immaniġġjat minn OpenAI jawtentika lil ChatGPT bħala l-klijent, OAuth 2.1 jawtentika lill-utenti tiegħek, u lista ta’ IPs permessi—inklużi firxiet ippubblikati minn OpenAI għall-konnetturi ta’ ChatGPT, aġġornati awtomatikament—tista’ tiżdied, iżda qatt ma tissostitwixxi l-awtentikazzjoni.
Qabel ma tmur live: injetta l-kredenzjali permezz tal-maniġer tas-sigrieti tal-host tiegħek, ikkonfigura s-servent tal-awtorizzazzjoni u r-ridirezzjonijiet, issettja timeouts u limiti ta’ rata għal għodod għaljin jew viżibbli esternament, neħħi tweġibiet ta’ debug u dejta personali mhux meħtieġa, u vverifika li l-logs ma fihomx tokens jew riżultati sensittivi. Wara d-dispjegament, erġa’ għamel replay tal-MCP Inspector kontra l-indirizz tal-produzzjoni.
Evoluzzjoni mingħajr tkissir
Żomm l-ismijiet tal-għodod u l-iskemi ppubblikati kompatibbli lura: żid kampijiet jew għodod, iżda tiksrilx kuntratti eżistenti. Jekk il-metadejta tinbidel, aġġorna l-konnessjoni u erġa’ għamel replay tas-suite ta’ evalwazzjoni tiegħek qabel ma tissottometti. Għal interfaċċja, ibdel l-ID tar-riżorsa meta l-HTML, JavaScript, jew CSS jevolvu b’mod li jista’ jkisser komponent cached.
Tifkiriet dwar is-sigurtà
- L-input kollu tal-għodod mhuwiex affidabbli: ivvalidah u infurza l-awtorizzazzjoni fuq is-servent
- Itlob konferma għal kitbiet b’impatt għoli
- Żomm is-sigrieti u d-dejta sensittiva ‘l bogħod mill-metadejta u r-riżultati
- Irreġistra biżżejjed biex tinvestiga, iżda eskludi l-kredenzjali u d-dejta personali mhux meħtieġa
- Illimita r-rata ta’ azzjonijiet għaljin jew viżibbli esternament
Punti Ewlenin
- Servent imsemmi u b’verżjoni b’
instructionsqosra u trasversali - Għodda waħda għal kull azzjoni, b’titlu, deskrizzjoni tal-intenzjoni, skemi, annotazzjonijiet, u awtorizzazzjoni fl-handle
structuredContentkonformi mal-iskema tal-output,isError: truegħal żbalji tan-negozju, xejn sigriet f’_meta- Pubblikazzjoni: HTTPS stabbli u pubbliku permezz ta’ streamable HTTP; is-Secure MCP Tunnel mhuwiex biżżejjed
- Kuntratti kompatibbli lura u IDs tar-riżorsi b’verżjoni