MCP serveris: įrankiai, rezultatai ir diegimas
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. remiantis „Build an MCP server“ puslapiu iš „OpenAI Plugins“ dokumentacijos ir MCP TypeScript SDK kodu (1.32.2). Ankstesnėje pamokoje buvo aprašyti „veiksmai“ (
defineAction,ActionError) iš neegzistuojančio SDK; dabar šį vaidmenį atlieka MCP įrankiai. Šaltiniai: Build an MCP server · MCP TypeScript SDK.
Serveris, jo tapatybė ir instrukcijos
Sukurk MCP serverį su stabiliu pavadinimu ir versija. Inicializacijos metu jis gali grąžinti lauką instructions, kurį „ChatGPT“ ir „Codex“ nuskaitys kartu su įrankių metaduomenimis. Šį lauką rezervuok gairėms, taikomoms visiems įrankiams – pavyzdžiui, privalomai kvietimų eiliškumui arba bendram užklausų dažnio limitui – ir pagrindinį turinį laikyk ne ilgesnį nei 512 simbolių. Nenukopijuok čia įrankių aprašymų ir nebandyk pakeisti modelio asmenybės.
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.",
}
);
Vienas įrankis vienam veiksmui
Kiekvienam skirtingam veiksmui sukurk atskirą įrankį: list_projects, get_project, update_project, o ne vieną universalų įrankį su daugybe režimų. Kiekvienas įrankis derina veiksmu orientuotą pavadinimą, skaitomą antraštę, aprašymą, paaiškinantį, kada jį naudoti, aiškią įvesties schemą, išvesties schemą (jei grąžinami struktūrizuoti duomenys), tikslias anotacijas ir tvarkyklę, kuri prieš imdamasi veiksmų autorizuoja užklausą. Modelis remiasi šiais metaduomenimis spręsdamas, ar ir kaip iškviesti įrankį – laikyk tai naudotojo patirties dalimi.
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 ir loadProject yra tavo pačių funkcijos. Svarbiausia – jų vieta: autorizacija vyksta serveryje, su kiekviena užklausa. Niekada nesiremk modeliu spręsdamas, ar naudotojas turi leidimą pasiekti duomenis.
Naudingi rezultatai be sąsajos
Įrankio rezultatas gali turėti tris dalis:
structuredContent: glausti duomenys, kuriuos modelis gali patikrinti ir panaudoti vėlesniuose kvietimuose;content: tekstas ar kitas MCP turinys, padedantis jam atsakyti;_meta: duomenys, skirti klientui, paslėpti nuo modelio.
Grąžink pakankamai informacijos, kad modelis galėtų užbaigti darbą be vizualaus komponento, naudodamas stabilius ID, kuriuos vėlesni įrankiai galės pakartotinai panaudoti. Verta paminėti du SDK elgsenos aspektus. Įrankis, deklaruojantis outputSchema, visuose sėkminguose rezultatuose privalo grąžinti atitinkamą structuredContent; priešingu atveju SDK išmes validacijos klaidą. Verslo klaida – pavyzdžiui, nerastas projektas arba atmestas veiksmas – signalizuojama rezultatu su isError: true, prie kurio pridėtas paaiškinamasis tekstas, kurį modelis gali perduoti naudotojui; tokio tipo rezultatas apeina išvesties schemos validaciją.
Niekada neįtrauk į rezultatą slaptų raktų, prieigos tokenų ar nereikalingų asmens duomenų ir nelaikyk _meta saugia slėptuve: šis laukas paslėptas nuo modelio, bet nėra apsaugotas.
Anotacijos ir informacijos išgavimas (Elicitation)
Anotacijos turi atspindėti tikrąją įrankio elgseną: readOnlyHint nustatyk į true tik tada, jei įrankis nieko negali modifikuoti, destructiveHint į true, jei jis gali sukelti negrįžtamą arba sunkiai atšaukiamą poveikį, ir openWorldHint į true, jei jis liečia viešąjį internetą arba atvirus išorinius subjektus. Jos padeda „ChatGPT“ ir „Codex“ pasirinkti tinkamą patvirtinimo elgseną; jos nepakeičia autorizacijos, validacijos ar patvirtinimo logikos tavo serveryje.
Kai serveriui reikia struktūrizuotos informacijos, kurios trūksta kvietime – pavyzdžiui, datos arba pasirinkimo tarp dviejų variantų – jis gali jos paprašyti naudodamas elicitation (informacijos išgavimą) – tai MCP protokolo mechanizmas. Apribok tai tuo, ką naudotojas gali pagrįstai pateikti; niekada nenaudok jo slaptams rinkti arba įprastai autentifikacijai apeiti.
Kelios paskyros ir įmonės žinios
Du papildomi suderinamumo aspektai gerina integraciją. Norėdamas padėti naudotojams prijungti kelias paskyras, eksponuok profilio įrankį, kuris yra autorizuotas, skirtas tik skaitymui ir pažymėtas _meta["openai/profile"]: true. „OpenAI“ tai naudoja identifikuoti prijungtas paskyras ir padėti naudotojams jas atskirti. Profilį sudaro patikrinti užklausos įgaliojimai, o kiekvienas kvietimas lieka apribotas tais pačiais įgaliojimais.
„ChatGPT“ funkcija company knowledge (įmonės žinios) gali naudoti tavo serverio įrankius, skirtus tik skaitymui. Kad papildinys taptų tinkamu šaltiniu, įgyvendink standartines search ir fetch įrankių įvesties schemas, kitus įrankius, skirtus tik skaitymui, pažymėk readOnlyHint: true, ir grąžink absoliučius, naudotojo atidaromus URL adresus šaltiniams, kuriuos modelis turi cituoti.
Galinio taško diegimas
Viešam pateikimui reikia serverio stabiliu, viešai pasiekiamu HTTPS adresu. Šis galinis taškas turi palaikyti streamable HTTP transportą, atsakyti stabiliu URL (paprastai baigiančiu /mcp), atitikti tavo darbo eigų latencijos ir prieinamumo reikalavimus, pasiekti tavo paslaugas ir duomenis, išlaikyti autentifikacijos ir autorizacijos ribas bei generuoti žurnalus ir metrikas inicializacijos bei įrankių kvietimų nesėkmėms fiksuoti.
„OpenAI“ Secure MCP Tunnel leidžia prijungti privatų serverį prie „ChatGPT“, tačiau jis neatitinka viešo pateikimo reikalavimų, taip pat kaip ir laikinas tunelis ar lokalus adresas. Jei serveris turi likti privatus, prieš jį pastatyk viešą HTTPS proxy: mTLS, valdomas „OpenAI“, autentifikuoja „ChatGPT“ kaip klientą, OAuth 2.1 autentifikuoja tavo naudotojus, ir galima pridėti IP leidimų sąrašą – įskaitant „OpenAI“ paskelbtus „ChatGPT“ jungčių diapazonus, automatiškai atnaujinamus – tačiau jis niekada nepakeičia autentifikacijos.
Prieš paleidžiant: įdiek įgaliojimus naudodamas savo serverio slaptų valdyklę, sukonfigūruok autorizacijos serverį ir nukreipimus, nustatyk laiko limitus ir užklausų dažnio ribas brangiems arba išorėje matomiems įrankiams, pašalink derinimo atsakymus ir nereikalingus asmens duomenis, bei patikrink, ar žurnaluose nėra tokenų ar jautrių rezultatų. Po diegimo paleisk MCP Inspector prieš gamybinį adresą.
Tobulėjimas nepažeidžiant suderinamumo
Laikyk paskelbtus įrankių pavadinimus ir schemas atgaliniu būdu suderinamus: pridėk laukų ar įrankių, bet nelaužyk esamų sutarčių. Jei metaduomenys keičiasi, atnaujink ryšį ir prieš pateikdamas iš naujo paleisk savo vertinimų rinkinį. Sąsajai keičiant HTML, JavaScript ar CSS taip, kad tai galėtų sugadinti podėlyje esantį komponentą, pakeisk išteklio ID.
Saugumo priminimai
- Visa įrankių įvestis yra nepatikima: validuok ją ir serveryje užtikrink autorizaciją
- Reikalauk patvirtinimo didelės įtakos rašymo operacijoms
- Laikyk slaptus raktus ir jautrius duomenis nuošalyje nuo metaduomenų ir rezultatų
- Fiksuok pakankamai duomenų tyrimams, bet neįtrauk įgaliojimų ir nereikalingų asmens duomenų
- Taikyk užklausų dažnio ribojimą brangiems arba išorėje matomiems veiksmams
Svarbiausi punktai
- Pavadinimą ir versiją turintis serveris su trumpomis, viską apimančiomis
instructions - Vienas įrankis vienam veiksmui, turintis antraštę, paskirties aprašymą, schemas, anotacijas ir autorizaciją tvarkyklėje
structuredContent, atitinkantis išvesties schemą,isError: trueverslo klaidoms, jokių paslapčių lauke_meta- Publikavimas: stabilus, viešas HTTPS per streamable HTTP; „Secure MCP Tunnel“ nepakanka
- Atgaliniu būdu suderinamos sutartys ir versijuoti išteklių ID