MCP-serveren: Værktøjer, resultater og implementering
På denne side
Lektionen er omskrevet den 3. november 2026 baseret på siden Build an MCP server fra OpenAI Plugins-dokumentationen og MCP TypeScript SDK-koden (1.32.2). Den tidligere lektion beskrev “actions” (
defineAction,ActionError) fra et ikke-eksisterende SDK; denne rolle tilhører nu MCP-værktøjer. Kilder: Build an MCP server · MCP TypeScript SDK.
Serveren, dens identitet og dens instrukser
Opret en MCP-server med et stabilt navn og en versionsnummer. Under initialiseringen kan den også returnere et instructions-felt, som ChatGPT og Codex læser sammen med værktøjets metadata. Brug dette felt til retningslinjer, der gælder for alle værktøjer – f.eks. en obligatorisk kaldesekvens eller en fælles rategrænse – og hold kernindholdet inden for de første 512 tegn. Kopier ikke værktøjsbeskrivelser hertil, og forsøg ikke at ændre modellens personlighed.
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.",
}
);
Ét værktøj pr. handling
Opret ét værktøj for hver distinkt handling: list_projects, get_project, update_project, frem for ét enkelt alt-i-et-værktøj med utallige tilstande. Hvert værktøj kombinerer et handlingsorienteret navn, en læsbar titel, en beskrivelse, der forklarer, hvornår det skal bruges, et eksplicit input-skema, et output-skema, hvis det returnerer strukturerede data, præcise annotationer og en handler, der godkender anmodningen, før den handler. Modellen bruger disse metadata til at beslutte, om og hvordan værktøjet skal kaldes – behandl det som en del af brugeroplevelsen.
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 og loadProject er dine egne funktioner. Det afgørende punkt er deres placering: godkendelse sker på serveren ved hver eneste anmodning. Stol aldrig på, at modellen beslutter, om en bruger har tilladelse til at få adgang til data.
Nyttige resultater uden en grænseflade
Et værktøjsresultat kan indeholde tre ting:
structuredContent: koncise data, som modellen kan inspicere og genbruge i efterfølgende kald;content: tekst eller andet MCP-indhold, der hjælper den med at svare;_meta: data beregnet til klienten, skjult for modellen.
Returner nok information til, at modellen kan fuldføre opgaven uden en visuel komponent, ved hjælp af stabile ID’er, som efterfølgende værktøjer kan genbruge. To SDK-adfærdsmønstre er værd at bemærke. Et værktøj, der erklærer et outputSchema, skal returnere compliant structuredContent i alle succesfulde resultater; ellers kaster SDK’en en valideringsfejl. En forretningsfejl – f.eks. et manglende projekt eller en nægtet handling – signaleres ved et resultat med isError: true ledsaget af forklarende tekst, som modellen kan videresende til brugeren; denne type resultat springer validering af output-skemaet over.
Medtag aldrig hemmeligheder, adgangstokens eller unødvendige personlige data i et resultat, og betragt ikke _meta som et sikkert skjulested: dette felt er skjult for modellen, men det er ikke beskyttet.
Annotationer og indhentning
Annotationer skal afspejle værktøjets faktiske adfærd: sæt readOnlyHint til true kun hvis det ikke kan ændre noget, destructiveHint til true hvis det kan forårsage en irreversibel eller svær at fortryde effekt, og openWorldHint til true hvis det rører ved det offentlige internet eller åbne eksterne enheder. De hjælper ChatGPT og Codex med at vælge den rigtige bekræftelsesadfærd; de erstatter ikke godkendelse, validering eller bekræftelseslogik på din server.
Når serveren har brug for strukturerede oplysninger, der mangler i kaldet – f.eks. en dato eller et valg mellem to muligheder – kan den anmode om dem via elicitation, en MCP-protokolmekanisme. Begræns dette til det, brugeren rimeligt kan levere; brug det aldrig til at indsamle hemmeligheder eller omgå normal godkendelse.
Flere konti og virksomhedsviden
To valgfrie kompatibiliteter forbedrer integrationen. For at hjælpe brugere, der forbinder flere konti, skal du eksponere et profilværktøj, der er godkendt, skrivebeskyttet og markeret med _meta["openai/profile"]: true. OpenAI bruger dette til at identificere forbundne konti og hjælpe brugere med at skelne mellem dem. Profilen er afledt af anmodningens validerede legitimationsoplysninger, og hvert kald forbliver begrænset til disse legitimationsoplysninger.
ChatGPT-funktionen company knowledge kan bruge din servers skrivebeskyttede værktøjer. For at gøre et plugin berettiget som kilde skal du implementere standardskemaerne for input til search- og fetch-værktøjer, markere andre skrivebeskyttede værktøjer med readOnlyHint: true og returnere absolutte, brugeråbnelige URL’er til kilder, som modellen skal citere.
Implementering af endpointet
Offentlig indsendelse kræver en server på en stabil, offentligt tilgængelig HTTPS-adresse. Dette endpoint skal understøtte streamable HTTP-transport, svare på en stabil URL (typisk sluttende på /mcp), opfylde latens- og tilgængelighedskravene i dine workflows, nå dine tjenester og data, bevare grænser for godkendelse og autorisation samt producere logs og målinger for initialiserings- og værktøjskaldsfejl.
OpenAI’s Secure MCP Tunnel giver dig mulighed for at forbinde en privat server til ChatGPT, men det opfylder ikke kravene til offentlig indsendelse, det gør en midlertidig tunnel eller lokal adresse heller ikke. Hvis serveren skal forblive privat, skal du placere en offentlig HTTPS-proxy foran den: mTLS administreret af OpenAI godkender ChatGPT som klienten, OAuth 2.1 godkender dine brugere, og en IP-allowlist – inklusive intervaller udgivet af OpenAI til ChatGPT-connectors, opdateret automatisk – kan tilføjes, men erstatter aldrig godkendelse.
Før du går live: injicer legitimationsoplysninger via din hosts hemmelighedsadministrator, konfigurér autorisationsserveren og omdirigeringerne, sæt timeouts og rategrænser for dyre eller eksternt synlige værktøjer, fjern debug-svar og unødvendige personlige data, og verificér, at logs ikke indeholder tokens eller følsomme resultater. Efter implementering skal du afspille MCP Inspector mod produktionsadressen.
Udvikling uden at bryde noget
Hold publicerede værktøjsnavne og -skemaer bagudkompatible: tilføj felter eller værktøjer, men bryd ikke eksisterende kontrakter. Hvis metadata ændres, skal du opdatere forbindelsen og afspille din evalueringssuite før indsendelse. For en grænseflade skal du ændre ressource-ID’et, når HTML, JavaScript eller CSS udvikler sig på en måde, der kunne bryde en cachelagret komponent.
Sikkerhedspåmindelser
- Alt værktøjsinput er ikke-betroet: valider det og håndhæv godkendelse på serveren
- Kræv bekræftelse for skrivninger med stor effekt
- Hold hemmeligheder og følsomme data ude af metadata og resultater
- Log nok til at kunne undersøge problemer, men udelad legitimationsoplysninger og unødvendige personlige data
- Rate-begræns dyre eller eksternt synlige handlinger
Vigtige pointer
- En navngivet, versioneret server med korte, tværgående
instructions - Ét værktøj pr. handling, med titel, intentsbeskrivelse, skemaer, annotationer og godkendelse i handleren
structuredContentcompliant med output-skemaet,isError: truefor forretningsfejl, intet hemmeligt i_meta- Publicering: stabil, offentlig HTTPS via streamable HTTP; Secure MCP Tunnel er utilstrækkelig
- Bagudkompatible kontrakter og versionerede ressource-ID’er