MCP server: tööriistad, tulemused ja kasutuselevõtt
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026, tuginedes OpenAI pluginate dokumentatsiooni lehele Build an MCP server ja MCP TypeScript SDK koodile (1.32.2). Eelmine õppetund kirjeldas „tegevusi“ (
defineAction,ActionError) olematust SDK-st; selle rolli on nüüd üle võtnud MCP tööriistad. Allikad: Build an MCP server · MCP TypeScript SDK.
Server, selle identiteet ja juhised
Loo MCP server stabiilse nime ja versiooniga. Initsialiseerimise käigus saab see tagastada välja instructions, mida ChatGPT ja Codex loevad koos tööriistade metaandmetega. Kasuta seda välja ainult üldiste juhiste jaoks, mis kehtivad kõigi tööriistade kohta – näiteks kohustuslik kutsejärjestus või ühine kiirusepiirang – ja hoia põhisisu esimese 512 märgi piires. Ära kopeeri siia tööriistade kirjeldusi ja ära püüa muuta mudeli isiksust.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Enne projekti muutmist helista get_project, et kinnitada selle ID ja olek.",
}
);
Üks tööriist ühe tegevuse kohta
Loo iga eraldiseisva tegevuse jaoks üks tööriist: list_projects, get_project, update_project, mitte üks universaalne tööriist paljude režiimidega. Iga tööriist ühendab tegevusele viitava nime, loetava pealkirja, kirjelduse, mis selgitab, millal seda kasutada, selge sisendiskeemi, väljundiskeemi (kui tagastatakse struktureeritud andmeid), täpsed annotatsioonid ja käitleja, mis autentib päringu enne tegutsemist. Mudel tugeneb nende metaandmete otsustamisel, kas ja kuidas tööriista kutsuda – kohtle seda kasutajakogemuse osana.
import { z } from "zod";
const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });
server.registerTool(
"get_project",
{
title: "Vaata projekti",
description:
"Kasuta, kui kasutaja soovib üksikasju konkreetse projekti kohta oma Acme tööruumis. " +
"Nõuab ID-d, mille tagastas 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); // Sinu juurdepääsu kontroll (Õppetund 8)
const found = await loadProject(user, id); // Sinu andmejuurdepääs
if (!found) {
return {
isError: true,
content: [{ type: "text", text: `Ühtegi projekti ${id} ei ole selle kontoga ligipääsetav.` }],
};
}
return {
structuredContent: { project: found },
content: [{ type: "text", text: `Projekt "${found.name}" (${found.status}).` }],
};
}
);
authenticate ja loadProject on sinu enda funktsioonid. Kriitiline on nende asukoht: autoriseerimine toimub serveris iga päringu korral. Ära kunagi tugine mudelile otsustamisel, kas kasutajal on andmetele juurdepääsu õigus.
Kasulikud tulemused ilma liideseta
Tööriista tulemus võib sisaldada kolme asja:
structuredContent: lühike andmestik, mida mudel saab kontrollida ja järgnevates kutsetes uuesti kasutada;content: tekst või muu MCP sisu, mis aitab sellel vastata;_meta: andmed, mis on mõeldud kliendile ja peidetud mudeli eest.
Tagasta piisavalt teavet, et mudel saaks töö lõpule viia ilma visuaalse komponendita, kasutades stabiilseid ID-sid, mida järgnevad tööriistad saavad uuesti kasutada. Tähelepanu väärib kaks SDK käitumist. Tööriist, mis deklareerib outputSchema, peab kõikides edukates tulemustes tagastama nõuetele vastava structuredContent; vastasel juhul viskab SDK valideerimisvea. Äritegevuse viga – näiteks puuduv projekt või keelatud tegevus – signaliseeritakse tulemusega, millel on isError: true, koos selgitava tekstiga, mida mudel saab kasutajale edastada; seda tüüpi tulemus möödub väljundiskeemi valideerimisest.
Ära kunagi lisa tulemustesse salasõnu, juurdepääsutokeneid ega ebavajalikke isikuandmeid ja ära kohtle _meta turvalise peidukohana: see väli on mudeli eest peidetud, kuid see ei ole kaitstud.
Annotatsioonid ja teabe pärimine
Annotatsioonid peavad peegeldama tööriista tegelikku käitumist: määra readOnlyHint väärtuseks true ainult siis, kui see ei saa midagi muuta, destructiveHint väärtuseks true, kui see võib põhjustada pöördumatut või raskesti tühistatavat mõju, ja openWorldHint väärtuseks true, kui see puudutab avalikku internetti või avatud väliseid üksusi. Need aitavad ChatGPT-l ja Codexil valida õiget kinnituskäitumist; need ei asenda autoriseerimist, valideerimist ega kinnitusloogikat sinu serveris.
Kui server vajab struktureeritud teavet, mida kutsest puudub – näiteks kuupäeva või valikut kahe variandi vahel –, saab seda taotleda teabe pärimise (elicitation) kaudu, mis on MCP protokolli mehhanism. Piira seda sellega, mida kasutaja mõistlikult pakkuda saab; ära kasuta seda saladuste kogumiseks ega tavalise autentimise möödahiilimiseks.
Mitu kontot ja ettevõtte teadmised
Integratsiooni parandavad kaks valikulist ühilduvust. Et aidata kasutajaid, kes ühendavad mitut kontot, exposeeri profiili tööriist, mis on autentitud, ainult lugemisõigusega ja märgitud _meta["openai/profile"]: true. OpenAI kasutab seda ühendatud kontode tuvastamiseks ja kasutajatele nende eristamiseks abistamiseks. Profiil tuletatakse päringu valideeritud mandaatidest ja iga kutse jääb piiratuks nende mandaatidega.
ChatGPT funktsioon ettevõtte teadmised (company knowledge) saab kasutada sinu serveri ainult lugemisõigusega tööriistu. Plugina allikana sobivaks muutmiseks rakenda standardseid sisendiskeeme search ja fetch tööriistadele, märgi teised ainult lugemisõigusega tööriistad readOnlyHint: true-ga ja tagasta absoluutsed, kasutaja poolt avatavad URL-id allikatele, mida mudel peab tsiteerima.
Lõpp-punkti kasutuselevõtt
Avalik esitamine nõuab serverit stabiilsel, avalikult kättesaadaval HTTPS-aadressil. See lõpp-punkt peab toetama streamable HTTP transporti, vastama stabiilsel URL-il (tavaliselt lõpeb /mcp), vastama sinu töövoogude latentsus- ja kättesaadavusnõuetele, jõudma sinu teenuste ja andmeteni, säilitama autentimis- ja autoriseerimispiire ning genereerima logisid ja mõõdikuid initsialiseerimise ja tööriistakutsete ebaõnnestumiste kohta.
OpenAI Secure MCP Tunnel võimaldab ühendada privaatse serveri ChatGPT-ga, kuid see ei vasta avaliku esitamise nõuetele, nagu ei tee seda ka ajutine tunnel või kohalik aadress. Kui server peab jääma privaatseks, paiguta selle ette avalik HTTPS-puhverserver: mTLS, mida haldab OpenAI, autentib ChatGPT kliendina, OAuth 2.1 autentib sinu kasutajaid ja lisada saab IP-lubade nimekirja – sealhulgas OpenAI avaldatud vahemikud ChatGPT connectorite jaoks, mida uuendatakse automaatselt –, kuid see ei asenda kunagi autentimist.
Enne tööle minekut: sisesta mandaadid oma hosti saladuste halduri kaudu, konfigureeri autoriseerimisserver ja ümbersuunamised, määra ajapiirangud ja kiirusepiirangud kulukatele või väljapoole suunatud tööriistadele, eemalda silumisvastused ja ebavajalikud isikuandmed ning veendu, et logid ei sisaldaks tokeneid ega tundlikke tulemusi. Pärast kasutuselevõttu käivita MCP Inspector tootmisaadressil uuesti.
Arendamine ilma katkestusteta
Hoia avaldatud tööriistade nimed ja skeemid tagasiühilduvana: lisa välju või tööriistu, kuid ära riku olemasolevaid lepinguid. Kui metaandmed muutuvad, värskenda ühendust ja käivita oma hindamiskomplekt enne esitamist uuesti. Liidese puhul muuda ressursi ID-d, kui HTML, JavaScript või CSS muutuvad viisil, mis võib rikkuda vahemällu salvestatud komponenti.
Ohutusmeeldetuletused
- Kogu tööriistade sisend on usaldamatu: valideeri seda ja jõusta autoriseerimine serveris
- Nõua kinnitust suure mõjuga kirjutamistegevuste jaoks
- Hoia saladused ja tundlikud andmed metaandmetest ja tulemustest eemal
- Logi piisavalt uurimiseks, kuid jäta välja mandaadid ja ebavajalikud isikuandmed
- Piira kulukate või väljapoole suunatud tegevuste kiirust
Peamised punktid
- Nime ja versiooniga server lühikeste, üldiste
instructions-ega - Üks tööriist ühe tegevuse kohta koos pealkirja, kavatsuse kirjelduse, skeemide, annotatsioonide ja autoriseerimisega käitlejas
structuredContent, mis vastab väljundiskeemile,isError: trueäritegevuse vigade korral, mitte midagi saladuslikku_metas- Avaldamine: stabiilne, avalik HTTPS streamable HTTP kaudu; Secure MCP Tunnel ei piisa
- Tagasiühilduvad lepingud ja versioonitud ressursi ID-d