MCP serveris: rīki, rezultāti un izvietošana
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī, pamatojoties uz OpenAI spraudņu dokumentācijas lapu Build an MCP server un MCP TypeScript SDK kodu (1.32.2). Iepriekšējā nodarbībā aprakstītās “darbības” (
defineAction,ActionError) piederēja neeksistējošam SDK; šo lomu tagad veic MCP rīki. Avoti: Build an MCP server · MCP TypeScript SDK.
Serveris, tā identitāte un instrukcijas
Izveido MCP serveri ar stabilu nosaukumu un versiju. Inicializācijas laikā tas var atgriezt arī lauku instructions, ko ChatGPT un Codex lasa līdztekus rīku metadatiem. Rezervē šo lauku vadlīnijām, kas attiecas uz visiem rīkiem, piemēram, obligātai izsaukumu secībai vai kopīgam ātruma ierobežojumam, un uzturi pamatsaturu pirmajās 512 zīmēs. Neiekopē šeit rīku aprakstus un nemēģini mainīt modeļa personību.
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.",
}
);
Viens rīks katrai darbībai
Izveido vienu rīku katrai atsevišķai darbībai: list_projects, get_project, update_project, nevis vienu universālu rīku ar daudzām režīmiem. Katrs rīks apvieno uz darbību orientētu nosaukumu, lasāmu virsrakstu, aprakstu, kas skaidro, kad to lietot, eksplicītu ievades shēmu, izvades shēmu (ja tas atgriež strukturētus datus), precīzas anotācijas un apstrādātāju, kas autorizē pieprasījumu pirms darbības veikšanas. Modelis paļaujas uz šiem metadatiem, lai izlemtu, vai un kā izsaukt rīku – uzlūko to kā lietotāja pieredzes sastāvdaļu.
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 un loadProject ir tavas pašrakstītās funkcijas. Kritiski svarīgs ir to izvietojums: autorizācija notiek servera pusē pie katra pieprasījuma. Nekad nepaļaujies uz modeli, lai noteiktu, vai lietotājam ir tiesības piekļūt datiem.
Noderīgi rezultāti bez saskarnes
Rīka rezultāts var saturēt trīs lietas:
structuredContent: kodolīgi dati, kurus modelis var pārbaudīt un atkārtoti izmantot turpmākajos izsaukumos;content: teksts vai cits MCP saturs, kas palīdz tam sniegt atbildi;_meta: dati, kas paredzēti klientam un ir slēpti no modeļa.
Atgriez pietiekami daudz informācijas, lai modelis varētu pabeigt uzdevumu bez vizuālas sastāvdaļas, izmantojot stabilus ID, kurus turpmākie rīki var atkārtoti izmantot. Ir vērts atzīmēt divas SDK uzvedības īpatnības. Rīkam, kas deklarē outputSchema, visos veiksmīgos rezultātos ir jāatgriež atbilstošs structuredContent; pretējā gadījumā SDK izmet validācijas kļūdu. Biznesa kļūda, piemēram, trūkstošs projekts vai liegta darbība, tiek signalizēta ar rezultātu, kurā ir isError: true, kam pievienots skaidrojošs teksts, ko modelis var nodot lietotājam; šāda veida rezultāts apej izvades shēmas validāciju.
Nekad neiekļauj rezultātā noslēpumus, piekļuves pilnvaras vai liekus personas datus un neuztver _meta kā drošu slēptuvi: šis lauks ir slēpts no modeļa, bet tas nav aizsargāts.
Anotācijas un informācijas izprašana
Anotācijām ir jāatspoguļo rīka faktiskā uzvedība: iestati readOnlyHint uz true tikai tad, ja tas neko nevar modificēt, destructiveHint uz true, ja tas var izraisīt neatgriezenisku vai grūti atceļamu efektu, un openWorldHint uz true, ja tas pieskaras publiskajam internetam vai atvērtām ārējām vienībām. Tās palīdz ChatGPT un Codex izvēlēties pareizo apstiprināšanas uzvedību; tās neaizstāj autorizāciju, validāciju vai apstiprināšanas loģiku tavā serverī.
Kad serverim ir nepieciešama strukturēta informācija, kuras trūkst izsaukumā, piemēram, datums vai izvēle starp divām opcijām, tas to var pieprasīt, izmantojot elicitation (informācijas izprašanu) – MCP protokola mehānismu. Ierobežo to ar to, ko lietotājs saprātīgi var sniegt; nekad neizmanto to noslēpumu vākšanai vai parastās autentifikācijas apiešanai.
Vairāki konti un uzņēmuma zināšanas
Divas opcionālas saderības uzlabo integrāciju. Lai palīdzētu lietotājiem pieslēgt vairākus kontus, eksponē profila rīku, kas ir autentificēts, tikai lasāms un atzīmēts ar _meta["openai/profile"]: true. OpenAI to izmanto, lai identificētu pieslēgtos kontus un palīdzētu lietotājiem tos atšķirt. Profils tiek iegūts no pieprasījuma validētām akreditācijas datiem, un katrs izsaukums paliek ierobežots tikai ar šiem datiem.
ChatGPT funkcija company knowledge (uzņēmuma zināšanas) var izmantot tava servera tikai lasāmos rīkus. Lai padarītu spraudni piemērotu kā avotu, ievies standarta ievades shēmas rīkiem search un fetch, atzīmē citus tikai lasāmos rīkus ar readOnlyHint: true un atgriez absolūtus, lietotāja atveramus URL adreses avotiem, kuriem modelim ir jāatsaucas.
Galapunkta izvietošana
Publiska iesniegšana prasa serveri stabilā, publiski sasniedzamā HTTPS adresē. Šim galapunktam ir jāatbalsta streamable HTTP transports, jāatbild uz stabilu URL (parasti beidzas ar /mcp), jāatbilst tavu darbplūsmu latentuma un pieejamības prasībām, jāsasniedz tavi servisi un dati, jāsaglabā autentifikācijas un autorizācijas robežas un jāģenerē žurnāli un metrikas inicializācijas un rīku izsaukumu kļūdām.
OpenAI Secure MCP Tunnel ļauj pieslēgt privātu serveri ChatGPT, taču tas neatbilst publiskas iesniegšanas prasībām, tāpat kā pagaidu tunelis vai lokāla adrese. Ja serverim ir jāpaliek privātam, novieto priekšā publisku HTTPS starpniekserveri: mTLS, ko pārvalda OpenAI, autentificē ChatGPT kā klientu, OAuth 2.1 autentificē tavus lietotājus, un var pievienot IP atļaušanas sarakstu, tostarp OpenAI publicētos diapazonus ChatGPT konektoriem, kas tiek automātiski atjaunināti, taču tas nekad neaizstāj autentifikāciju.
Pirms došanās tiešsaistē: ievadi akreditācijas datus, izmantojot sava resursdatora noslēpumu pārvaldnieku, konfigurē autorizācijas serveri un pāradresācijas, iestati noildzes un ātruma ierobežojumus dārgiem vai ārēji redzamiem rīkiem, noņem atkļūdošanas atbildes un liekus personas datus, kā arī pārliecinies, ka žurnālos nav pilnvaru vai sensitīvu rezultātu. Pēc izvietošanas atkārto MCP Inspector testēšanu pret ražošanas adresi.
Attīstība, nelaužot saderību
Uzturi publicētos rīku nosaukumus un shēmas atpakaļsaderīgas: pievieno laukus vai rīkus, bet nelauz esošos līgumus. Ja metadati mainās, atsvaidzini savienojumu un atkārto savu novērtēšanas komplektu pirms iesniegšanas. Saskarnei maini resursa ID, ja HTML, JavaScript vai CSS attīstās tā, ka tas varētu sabojāt kešatmiņā saglabātu komponenti.
Drošības atgādinājumi
- Visa rīku ievade ir neuzticama: validē to un piespied autorizāciju servera pusē
- Piepras apstiprinājumu augstas ietekmes rakstīšanas darbībām
- Uzturi noslēpumus un sensitīvus datus ārpus metadatiem un rezultātiem
- Žurnalē pietiekami daudz, lai veiktu izmeklēšanu, bet izslēdz akreditācijas datus un liekus personas datus
- Ierobežo ātrumu dārgām vai ārēji redzamām darbībām
Galvenās atziņas
- Nosaukts, versijots serveris ar īsām, visaptverošām
instructions - Viens rīks katrai darbībai ar virsrakstu, nolūka aprakstu, shēmām, anotācijām un autorizāciju apstrādātājā
structuredContent, kas atbilst izvades shēmai,isError: truebiznesa kļūdām, nekādu noslēpumu laukā_meta- Publikācija: stabils, publisks HTTPS, izmantojot streamable HTTP; Secure MCP Tunnel nepietiek
- Atpakaļsaderīgi līgumi un versijoti resursu ID