Strežnik MCP: orodja, rezultati in uvedba
Na tej strani
Lekcija je bila ponovno napisana 3. novembra 2026 na podlagi strani Build an MCP server iz dokumentacije za vtičnike OpenAI in kode MCP TypeScript SDK (različica 1.32.2). Prejšnja lekcija je opisovala “akcije” (
defineAction,ActionError) iz neobstoječega SDK-ja; to vlogo zdaj prevzemajo orodja MCP. Viri: Build an MCP server · MCP TypeScript SDK.
Strežnik, njegova identiteta in navodila
Ustvari strežnik MCP s stabilnim imenom in različico. Med inicializacijo lahko vrne tudi polje instructions, ki ga ChatGPT in Codex prebereta skupaj z metapodatki orodij. To polje rezerviraj za smernice, ki veljajo za vsa orodja – kot je obvezen vrstni red klicev ali skupna omejitev hitrosti – in jedrnato vsebino ohrani v prvih 512 znakih. Sem ne kopiraj opisov orodij in ne poskušaj spremeniti osebnosti modela.
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.",
}
);
Eno orodje na akcijo
Za vsako ločeno akcijo ustvari posebno orodje: list_projects, get_project, update_project, namesto enega samega univerzalnega orodja z numerous načini. Vsako orodje združuje ime, usmerjeno v akcijo, berljiv naslov, opis, ki pojasnjuje, kdaj ga uporabiti, eksplicitno shemo vhoda, shemo izhoda (če vrača strukturirane podatke), natančne anotacije in rokodelnik (handler), ki pred izvedbo avtorizira zahtevo. Model se pri odločanju, ali in kako poklicati orodje, zanaša na te metapodatke – obravnavaj jih kot del uporabniške izkušnje.
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 in loadProject sta tvoji lastni funkciji. Ključna je njuna postavitev: avtorizacija poteka na strežniku, pri vsaki zahtevi. Nikoli se ne zanašaj na model, da bi se odločil, ali ima uporabnik dovoljenje za dostop do podatkov.
Uporabni rezultati brez vmesnika
Rezultat orodja lahko vsebuje tri stvari:
structuredContent: jedrnati podatki, ki jih model lahko pregleda in ponovno uporabi v naslednjih klicih;content: besedilo ali druga vsebina MCP, ki mu pomaga pri odgovoru;_meta: podatki, namenjeni odjemalcu, skriti modelu.
Vrni dovolj informacij, da lahko model dokonča nalogo brez vizualne komponente, z uporabo stabilnih ID-jev, ki jih lahko ponovno uporabijo naslednja orodja. Omeniti velja dva vidika delovanja SDK-ja. Orodje, ki deklarira outputSchema, mora v vseh uspešnih rezultatih vrniti skladno vsebino structuredContent; v nasprotnem primeru SDK vrže napako pri preverjanju veljavnosti. Poslovna napaka – kot je manjkajoč projekt ali zavrnjena akcija – se signalizira z rezultatom, ki ima isError: true, skupaj z razlagalnim besedilom, ki ga model lahko posreduje uporabniku; ta vrsta rezultata obide preverjanje sheme izhoda.
Nikoli ne vključuj skrivnosti, žetonov za dostop ali nepotrebnih osebnih podatkov v rezultat in ne obravnavaj _meta kot varnega skrivališča: to polje je modelu sicer skrito, vendar ni zaščiteno.
Anotacije in izsiljevanje informacij (elicitation)
Anotacije morajo odražati dejansko obnašanje orodja: readOnlyHint nastavi na true le, če orodje ne more ničesar spremeniti, destructiveHint na true, če lahko povzroči nepovraten ali težko razveljavljiv učinek, in openWorldHint na true, če se dotika javnega interneta ali odprtih zunanjih entitet. Pomagajo ChatGPT in Codex izbrati ustrezno obnašanje pri potrditvi; ne nadomeščajo pa logike avtorizacije, validacije ali potrditve na tvojem strežniku.
Ko strežnik potrebuje strukturirane informacije, ki manjkajo v klicu – kot je datum ali izbira med dvema možnostma – jih lahko zahteva prek mehanizma protokola MCP, imenovanega elicitation. To omeji na tisto, kar lahko uporabnik razumno zagotovi; nikoli ga ne uporabi za zbiranje skrivnosti ali obhod običajne avtentikacije.
Več računov in znanje podjetja
Dve opcijski združljivosti izboljšata integracijo. Da bi pomagal uporabnikom, ki povezujejo več računov, izpostavi orodje za profil, ki je avtenticirano, samo za branje in označeno z _meta["openai/profile"]: true. OpenAI to uporablja za identifikacijo povezanih računov in pomoč uporabnikom pri razlikovanju med njimi. Profil izhaja iz preverjenih poverilnic zahteve, vsak klic pa ostane omejen na te poverilnice.
Funkcija company knowledge v ChatGPT lahko uporablja tvoja strežniška orodja samo za branje. Da bi bil vtičnik upravičen kot vir, implementiraj standardne sheme vhoda za orodji search in fetch, druga orodja samo za branje označi z readOnlyHint: true in vrni absolutne URL-je, ki jih lahko uporabnik odpre, za vire, ki jih mora model navesti.
Uvedba končne točke
Javna objava zahteva strežnik na stabilnem, javno dosegljivem naslovu HTTPS. Ta končna točka mora podpirati prenos streamable HTTP, odgovarjati na stabilnem URL-ju (običajno se konča z /mcp), izpolnjevati zahteve glede zakasnitve in razpoložljivosti tvojih delovnih tokov, doseči tvoje storitve in podatke, ohranjati meje avtentikacije in avtorizacije ter proizvajati dnevnike in metrike za napake pri inicializaciji in klicih orodij.
Secure MCP Tunnel podjetja OpenAI ti omogoča povezavo zasebnega strežnika s ChatGPT, vendar ne izpolnjuje zahtev za javno objavo, prav tako ne začasni tunel ali lokalni naslov. Če mora strežnik ostati zaseben, predenj postavi javni posredniški strežnik HTTPS: mTLS, ki ga upravlja OpenAI, avtenticira ChatGPT kot odjemalca, OAuth 2.1 avtenticira tvoje uporabnike, dodatek seznama dovoljenih naslovov IP – vključno z obsegi, ki jih OpenAI objavlja za konektorje ChatGPT in se samodejno posodabljajo – je možen, vendar nikoli ne nadomešča avtentikacije.
Pred zagonom v živo: vnesi poverilnice prek upravitelja skrivnosti tvojega gostitelja, konfiguriraj strežnik za avtorizacijo in preusmeritve, nastavi časovne omejitve in omejitve hitrosti za draga ali navzven vidna orodja, odstrani odgovore za razhroščevanje in nepotrebne osebne podatke ter preveri, da dnevniki ne vsebujejo žetonov ali občutljivih rezultatov. Po uvedbi ponovno zaženi MCP Inspector proti produkcijskemu naslovu.
Razvoj brez prekinitev
Objavljena imena orodij in sheme ohrani združljive nazaj: dodajaj polja ali orodja, vendar ne krši obstoječih pogodb. Če se metapodatki spremenijo, osveži povezavo in pred objavo ponovno zaženi svoj evalvacijski niz. Za vmesnik spremeni ID vira, ko se HTML, JavaScript ali CSS spremenita tako, da bi lahko prekinila predpomnjeno komponento.
Opomniki o varnosti
- Vsi vhodi orodij so nezaupljivi: validiraj jih in uveljavi avtorizacijo na strežniku
- Zahtevaj potrditev za zapisovanja z velikim vplivom
- Skrivnosti in občutljive podatke ohrani zunaj metapodatkov in rezultatov
- Beleži dovolj za preiskavo, vendar izključi poverilnice in nepotrebne osebne podatke
- Omeji hitrost dragih ali navzven vidnih akcij
Ključne ugotovitve
- Imenovan in različičen strežnik s kratkimi, prečnimi
instructions - Eno orodje na akcijo z naslovom, opisom namena, shemami, anotacijami in avtorizacijo v rokodelniku
structuredContentskladen s shemo izhoda,isError: trueza poslovne napake, nič skrivnostnega v_meta- Objava: stabilen, javen HTTPS prek streamable HTTP; Secure MCP Tunnel ni zadosten
- Pogodbe, združljive nazaj, in različičeni ID-ji virov