MCP-servern: Verktyg, resultat och distribution
På denna sida
Lektionen omskriven den 3 november 2026 baserat på sidan Build an MCP server från OpenAI:s plugin-dokumentation och MCP TypeScript SDK-koden (1.32.2). Den tidigare lektionen beskrev “actions” (
defineAction,ActionError) från ett SDK som inte existerar; denna roll tillhör nu MCP-verktyg. Källor: Build an MCP server · MCP TypeScript SDK.
Servern, dess identitet och instruktioner
Skapa en MCP-server med ett stabilt namn och versionsnummer. Vid initiering kan den också returnera ett fält instructions som ChatGPT och Codex läser tillsammans med verktygsmetadatan. Reservera detta fält för riktlinjer som gäller alla verktyg – till exempel en obligatorisk anropsordning eller en gemensam hastighetsbegränsning – och håll kärninnehållet inom de första 512 tecknen. Kopiera inte verktygsbeskrivningar hit och försök inte ändra modellens personlighet.
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.",
}
);
Ett verktyg per åtgärd
Skapa ett verktyg för varje distinkt åtgärd: list_projects, get_project, update_project, snarare än ett enda generellt verktyg med många lägen. Varje verktyg kombinerar ett handlingsinriktat namn, en läsbar titel, en beskrivning som förklarar när det ska användas, ett explicit inmatningsschema, ett utmatningsschema om det returnerar strukturerad data, precisa annoteringar och en hanterare som auktoriserar begäran innan den agerar. Modellen förlitar sig på denna metadata för att avgöra om och hur verktyget ska anropas – behandla det som en del av användarupplevelsen.
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 och loadProject är dina egna funktioner. Det avgörande är var de placeras: auktoriseringen sker på servern, vid varje begäran. Lita aldrig på modellen för att avgöra om en användare har behörighet att komma åt data.
Användbara resultat utan gränssnitt
Ett verktygsresultat kan innehålla tre saker:
structuredContent: koncis data som modellen kan inspektera och återanvända i efterföljande anrop;content: text eller annat MCP-innehåll som hjälper den att svara;_meta: data avsedd för klienten, dold för modellen.
Returnera tillräckligt med information för att modellen ska kunna slutföra uppgiften utan en visuell komponent, genom att använda stabila ID:n som efterföljande verktyg kan återanvända. Två SDK-beteenden är värda att notera. Ett verktyg som deklarerar ett outputSchema måste returnera compliant structuredContent i alla lyckade resultat; annars kastar SDK:t ett valideringsfel. Ett affärsmässigt fel – till exempel ett saknat projekt eller en nekad åtgärd – signaleras av ett resultat med isError: true åtföljt av förklarande text som modellen kan vidarebefordra till användaren; denna typ av resultat kringgår validering av utmatningsschemat.
Inkludera aldrig hemligheter, åtkomsttoken eller onödiga personuppgifter i ett resultat, och behandla inte _meta som en säker gömställe: detta fält är dolt för modellen, men det är inte skyddat.
Annoteringar och inhämtning
Annoteringar måste spegla verktygets faktiska beteende: sätt readOnlyHint till true endast om det inte kan modifiera något, destructiveHint till true om det kan orsaka en irreversibel eller svår att ångra effekt, och openWorldHint till true om det berör det publika internet eller öppna externa entiteter. De hjälper ChatGPT och Codex att välja rätt bekräftelsebeteende; de ersätter inte auktorisering, validering eller bekräftelselogik på din server.
När servern behöver strukturerad information som saknas i anropet – till exempel ett datum eller ett val mellan två alternativ – kan den begära detta via elicitation, en mekanism i MCP-protokollet. Begränsa detta till vad användaren rimligen kan tillhandahålla; använd det aldrig för att samla in hemligheter eller kringgå normal autentisering.
Flera konton och företagskunskap
Två valfria kompatibiliteter förbättrar integrationen. För att hjälpa användare som ansluter flera konton, exponera ett profilverktyg som är autentiserat, skrivskyddat och märkt _meta["openai/profile"]: true. OpenAI använder detta för att identifiera anslutna konton och hjälpa användare att skilja mellan dem. Profilen härleds från begärans validerade autentiseringsuppgifter, och varje anrop förblir begränsat till dessa uppgifter.
ChatGPT:s funktion company knowledge kan använda din servers skrivskyddade verktyg. För att göra ett plugin berättigat som källa, implementera standardscheman för inmatning för search- och fetch-verktyg, märk andra skrivskyddade verktyg med readOnlyHint: true, och returnera absoluta, användaröppningsbara URL:er för källor som modellen måste citera.
Distribuera slutpunkten
Offentlig publicering kräver en server på en stabil, offentligt tillgänglig HTTPS-adress. Denna slutpunkt måste stödja transporten streamable HTTP, svara på en stabil URL (som vanligtvis slutar på /mcp), möta latens- och tillgänglighetskraven för dina arbetsflöden, nå dina tjänster och data, bevara gränserna för autentisering och auktorisering, samt producera loggar och mätvärden för initiering och misslyckade verktygsanrop.
OpenAI:s Secure MCP Tunnel låter dig ansluta en privat server till ChatGPT, men det uppfyller inte kraven för offentlig publicering, inte heller gör en tillfällig tunnel eller lokal adress. Om servern måste förbli privat, placera en offentlig HTTPS-proxy framför den: mTLS hanterat av OpenAI autentiserar ChatGPT som klient, OAuth 2.1 autentiserar dina användare, och en IP-allowlist – inklusive intervall publicerade av OpenAI för ChatGPT-kontakter, uppdaterade automatiskt – kan läggas till, men får aldrig ersätta autentisering.
Innan du går live: injicera autentiseringsuppgifter via din värds hemlighetshanterare, konfigurera auktoriseringsservern och omdirigeringar, ställ in tidsgränser och hastighetsbegränsningar för dyra eller externt synliga verktyg, ta bort felsvar och onödiga personuppgifter, och verifiera att loggarna inte innehåller token eller känsliga resultat. Efter distributionen, kör MCP Inspector igen mot produktionsadressen.
Utvecklas utan att gå sönder
Håll publicerade verktygsnamn och scheman bakåtkompatibla: lägg till fält eller verktyg, men bryt inte befintliga kontrakt. Om metadata ändras, uppdatera anslutningen och kör din utvärderingssvit igen innan du skickar in. För ett gränssnitt, ändra resurs-ID:t när HTML, JavaScript eller CSS utvecklas på ett sätt som kan bryta en cachad komponent.
Påminnelser om säkerhet
- All verktygsinmatning är icke-betrodd: validera den och tillämpa auktorisering på servern
- Kräv bekräftelse för skrivoperationer med stor påverkan
- Håll hemligheter och känslig data borta från metadata och resultat
- Logga tillräckligt för att kunna undersöka, men exkludera autentiseringsuppgifter och onödiga personuppgifter
- Hastighetsbegränsa dyra eller externt synliga åtgärder
Viktiga punkter
- En namngiven, versionerad server med korta, övergripande
instructions - Ett verktyg per åtgärd, med titel, avsiktsbeskrivning, scheman, annoteringar och auktorisering i hanteraren
structuredContentsom följer utmatningsschemat,isError: trueför affärsmässiga fel, inga hemligheter i_meta- Publicering: stabil, offentlig HTTPS via streamable HTTP; Secure MCP Tunnel räcker inte
- Bakåtkompatibla kontrakt och versionerade resurs-ID:n