Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

De MCP-server: tools, resultaten en implementatie

Les 5 van 14 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. De server, zijn identiteit en instructies
  2. Één tool per actie
  3. Nuttige resultaten zonder interface
  4. Annotaties en elicitation
  5. Meerdere accounts en bedrijfskennis
  6. Het endpoint implementeren
  7. Evolueren zonder te breken
  8. Herinneringen aan beveiliging
  9. Belangrijkste punten

Les herschreven op 3 november 2026 op basis van de pagina Build an MCP server uit de OpenAI Plugins-documentatie en de MCP TypeScript SDK-code (1.32.2). De vorige les beschreef “actions” (defineAction, ActionError) van een niet-bestaande SDK; deze rol is nu weggelegd voor MCP-tools. Bronnen: Build an MCP server · MCP TypeScript SDK.

De server, zijn identiteit en instructies

Maak een MCP-server met een stabiele naam en versie. Tijdens de initialisatie kan de server ook een veld instructions retourneren dat ChatGPT en Codex lezen naast de tool-metadata. Reserveer dit veld voor richtlijnen die voor alle tools gelden, zoals een verplichte oproepvolgorde of een gedeelde snelheidsbeperking, en houd de kerninhoud binnen de eerste 512 tekens. Plak hier geen tool-beschrijvingen en probeer niet de persoonlijkheid van het model te veranderen.

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.",
  }
);

Één tool per actie

Maak voor elke afzonderlijke actie één tool: list_projects, get_project, update_project, in plaats van één allesomvattende tool met talloze modi. Elke tool combineert een op actie gerichte naam, een leesbare titel, een beschrijving die uitlegt wanneer deze gebruikt moet worden, een expliciet invoerschema, een uitvoerschema (als er gestructureerde gegevens worden geretourneerd), precieze annotaties en een handler die het verzoek autoriseert voordat er actie wordt ondernomen. Het model vertrouwt op deze metadata om te beslissen of en hoe de tool wordt aangeroepen; beschouw dit als onderdeel van de gebruikerservaring.

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 en loadProject zijn uw eigen functies. Het cruciale punt is hun plaatsing: autorisatie vindt plaats op de server, bij elk verzoek. Vertrouw er nooit op dat het model beslist of een gebruiker toestemming heeft om gegevens te openen.

Nuttige resultaten zonder interface

Een tool-resultaat kan drie dingen bevatten:

  • structuredContent: beknopte gegevens die het model kan inspecteren en hergebruiken in daaropvolgende oproepen;
  • content: tekst of andere MCP-inhoud die helpt bij het beantwoorden van de vraag;
  • _meta: gegevens bestemd voor de client, verborgen voor het model.

Retourneer voldoende informatie zodat het model de taak kan voltooien zonder visuele component, met behulp van stabiele ID’s die daaropvolgende tools kunnen hergebruiken. Twee SDK-gedragingen zijn het vermelden waard. Een tool die een outputSchema declareert, moet bij alle succesvolle resultaten conform structuredContent retourneren; anders gooit de SDK een validatiefout. Een bedrijfsfout, zoals een ontbrekend project of een geweigerde actie, wordt gesignaleerd door een resultaat met isError: true, vergezeld van verklarende tekst die het model aan de gebruiker kan doorgeven; dit type resultaat slaat de validatie van het uitvoerschema over.

Neem nooit geheimen, access tokens of onnodige persoonlijke gegevens op in een resultaat, en beschouw _meta niet als een veilige verstopplek: dit veld is weliswaar verborgen voor het model, maar het is niet beveiligd.

Annotaties en elicitation

Annotaties moeten het daadwerkelijke gedrag van de tool weerspiegelen: stel readOnlyHint alleen in op true als er niets gewijzigd kan worden, destructiveHint op true als er een onomkeerbaar of moeilijk ongedaan te maken effect kan optreden, en openWorldHint op true als er contact wordt gemaakt met het openbare internet of open externe entiteiten. Ze helpen ChatGPT en Codex het juiste bevestigingsgedrag te kiezen; ze vervangen geen autorisatie, validatie of bevestigingslogica op uw server.

Wanneer de server gestructureerde informatie nodig heeft die ontbreekt in de oproep, zoals een datum of een keuze tussen twee opties, kan deze daarom vragen via elicitation, een mechanisme van het MCP-protocol. Beperk dit tot wat de gebruiker redelijkerwijs kan leveren; gebruik het nooit om geheimen te verzamelen of normale authenticatie te omzeilen.

Meerdere accounts en bedrijfskennis

Twee optionele compatibiliteiten verbeteren de integratie. Om gebruikers te helpen die meerdere accounts verbinden, exposeert u een profiel-tool die geauthenticeerd en alleen-lezen is, en gemarkeerd met _meta["openai/profile"]: true. OpenAI gebruikt dit om verbonden accounts te identificeren en gebruikers te helpen onderscheid te maken tussen hen. Het profiel is afgeleid van de gevalideerde referenties van het verzoek, en elke oproep blijft beperkt tot die referenties.

De functie company knowledge van ChatGPT kan gebruikmaken van de alleen-lezen tools van uw server. Om een plugin als bron in aanmerking te laten komen, implementeert u de standaard invoerschema’s voor search- en fetch-tools, markeert u andere alleen-lezen tools met readOnlyHint: true, en retourneert u absolute, door de gebruiker te openen URL’s voor bronnen die het model moet citeren.

Het endpoint implementeren

Publieke indiening vereist een server op een stabiel, publiek bereikbaar HTTPS-adres. Dit endpoint moet streamable HTTP-transport ondersteunen, reageren op een stabiele URL (doorgaans eindigend op /mcp), voldoen aan de latentie- en beschikbaarheidseisen van uw workflows, uw services en gegevens bereiken, authenticatie- en autorisatiegrenzen behouden, en logs en metrieken produceren voor initialisatie en mislukte tool-aanroepen.

OpenAI’s Secure MCP Tunnel stelt u in staat een private server met ChatGPT te verbinden, maar voldoet niet aan de eisen voor publieke indiening, evenmin als een tijdelijke tunnel of lokaal adres. Als de server privé moet blijven, plaatst u er een openbare HTTPS-proxy voor: mTLS beheerd door OpenAI authenticeert ChatGPT als client, OAuth 2.1 authenticeert uw gebruikers, en een IP-allowlist, inclusief reeksen die door OpenAI voor ChatGPT-connectors zijn gepubliceerd en automatisch worden bijgewerkt, kan worden toegevoegd, maar vervangt nooit authenticatie.

Voordat u live gaat: injecteer referenties via de secret manager van uw host, configureer de autorisatieserver en omleidingen, stel time-outs en snelheidsbeperkingen in voor dure of extern zichtbare tools, verwijder debug-responsen en onnodige persoonlijke gegevens, en verifieer dat logs geen tokens of gevoelige resultaten bevatten. Na implementatie speelt u MCP Inspector af tegen het productieadres.

Evolueren zonder te breken

Houd gepubliceerde tool-namen en schema’s achterwaarts compatibel: voeg velden of tools toe, maar breek geen bestaande contracten. Als metadata verandert, vernieuwt u de verbinding en speelt u uw evaluatiesuite opnieuw af voordat u indient. Voor een interface wijzigt u de resource-ID wanneer HTML, JavaScript of CSS zodanig evolueert dat een gecachete component kan breken.

Herinneringen aan beveiliging

  • Alle tool-invoer is onbetrouwbaar: valideer deze en forceer autorisatie op de server
  • Vereis bevestiging voor schrijfbewerkingen met grote impact
  • Houd geheimen en gevoelige gegevens uit metadata en resultaten
  • Log voldoende om onderzoek mogelijk te maken, maar sluit referenties en onnodige persoonlijke gegevens uit
  • Stel snelheidsbeperkingen in voor dure of extern zichtbare acties

Belangrijkste punten

  • Een benoemde, geversioneerde server met korte, doorsnedende instructions
  • Één tool per actie, met een titel, intentiebeschrijving, schema’s, annotaties en autorisatie in de handler
  • structuredContent conform het uitvoerschema, isError: true voor bedrijfsfouten, niets geheims in _meta
  • Publicatie: stabiel, publiek HTTPS via streamable HTTP; de Secure MCP Tunnel is onvoldoende
  • Achterwaarts compatibele contracten en geversioneerde resource-ID’s