Der MCP-Server: Werkzeuge, Ergebnisse und Bereitstellung
Auf dieser Seite
Lektion am 3. November 2026 überarbeitet basierend auf der Seite Build an MCP server aus der OpenAI Plugins-Dokumentation und dem MCP TypeScript SDK-Code (1.32.2). Die vorherige Lektion beschrieb „Aktionen” (
defineAction,ActionError) aus einem nicht existierenden SDK; diese Rolle gehört nun den MCP-Werkzeugen. Quellen: Build an MCP server · MCP TypeScript SDK.
Der Server, seine Identität und seine Anweisungen
Erstellen Sie einen MCP-Server mit einem stabilen Namen und einer Version. Während der Initialisierung kann er auch ein Feld instructions zurückgeben, das ChatGPT und Codex zusammen mit den Werkzeugmetadaten lesen. Reservieren Sie dieses Feld für Richtlinien, die für alle Werkzeuge gelten – wie eine zwingende Reihenfolge der Aufrufe oder einen gemeinsamen Rate Limit – und halten Sie den Kerninhalt innerhalb der ersten 512 Zeichen. Kopieren Sie Werkzeugbeschreibungen nicht hierher und versuchen Sie nicht, die Persönlichkeit des Modells zu ändern.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Bevor Sie ein Projekt ändern, rufen Sie get_project auf, um dessen ID und Status zu bestätigen.",
}
);
Ein Werkzeug pro Aktion
Erstellen Sie für jede einzelne Aktion ein Werkzeug: list_projects, get_project, update_project, anstatt ein einziges Alleskönner-Werkzeug mit zahlreichen Modi. Jedes Werkzeug kombiniert einen handlungsorientierten Namen, einen lesbaren Titel, eine Beschreibung, die erklärt, wann es verwendet werden soll, ein explizites Eingabeschema, ein Ausgabeschema, falls es strukturierte Daten zurückgibt, präzise Annotationen und einen Handler, der die Anfrage vor der Ausführung autorisiert. Das Modell stützt sich auf diese Metadaten, um zu entscheiden, ob und wie es das Werkzeug aufruft – behandeln Sie dies als Teil der Benutzererfahrung.
import { z } from "zod";
const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });
server.registerTool(
"get_project",
{
title: "Projekt anzeigen",
description:
"Verwenden Sie dies, wenn der Benutzer Details zu einem bestimmten Projekt in seinem Acme-Arbeitsbereich wünscht. " +
"Erfordert die ID, die von list_projects zurückgegeben wird.",
inputSchema: { id: z.string().min(1) },
outputSchema: { project: project },
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async ({ id }, extra) => {
const user = await authenticate(extra); // Ihre Zugriffssteuerung (Lektion 8)
const found = await loadProject(user, id); // Ihr Datenzugriff
if (!found) {
return {
isError: true,
content: [{ type: "text", text: `Kein Projekt ${id} ist mit diesem Konto zugänglich.` }],
};
}
return {
structuredContent: { project: found },
content: [{ type: "text", text: `Projekt "${found.name}" (${found.status}).` }],
};
}
);
authenticate und loadProject sind Ihre eigenen Funktionen. Der entscheidende Punkt ist ihre Platzierung: Die Autorisierung erfolgt auf dem Server bei jeder Anfrage. Verlassen Sie sich niemals darauf, dass das Modell entscheidet, ob ein Benutzer berechtigt ist, auf Daten zuzugreifen.
Nützliche Ergebnisse ohne Schnittstelle
Ein Werkzeugergebnis kann drei Dinge tragen:
structuredContent: kompakte Daten, die das Modell inspizieren und in nachfolgenden Aufrufen wiederverwenden kann;content: Text oder andere MCP-Inhalte, die es bei der Antwort unterstützen;_meta: Daten, die für den Client bestimmt sind und vor dem Modell verborgen bleiben.
Geben Sie genügend Informationen zurück, damit das Modell die Aufgabe ohne visuelle Komponente abschließen kann, und verwenden Sie stabile IDs, die von nachfolgenden Werkzeugen wiederverwendet werden können. Zwei SDK-Verhaltensweisen sind erwähnenswert. Ein Werkzeug, das ein outputSchema deklariert, muss in allen erfolgreichen Ergebnissen konforme structuredContent zurückgeben; andernfalls wirft das SDK einen Validierungsfehler. Ein Geschäftsfehler – wie ein fehlendes Projekt oder eine verweigerte Aktion – wird durch ein Ergebnis mit isError: true signalisiert, begleitet von erläuterndem Text, den das Modell an den Benutzer weitergeben kann; dieses Ergebnis-Typ umgeht die Validierung des Ausgabeschemas.
Schließen Sie niemals Geheimnisse, Zugriffstoken oder unnötige personenbezogene Daten in einem Ergebnis ein, und behandeln Sie _meta nicht als sicheren Versteckort: Dieses Feld ist zwar vor dem Modell verborgen, aber nicht geschützt.
Annotationen und Elicitation
Annotationen müssen das tatsächliche Verhalten des Werkzeugs widerspiegeln: Setzen Sie readOnlyHint nur auf true, wenn es nichts ändern kann, destructiveHint auf true, wenn es irreversible oder schwer rückgängig zu machende Effekte verursachen kann, und openWorldHint auf true, wenn es das öffentliche Internet oder offene externe Entitäten berührt. Sie helfen ChatGPT und Codex, das richtige Bestätigungsverhalten zu wählen; sie ersetzen keine Autorisierung, Validierung oder Bestätigungslogik auf Ihrem Server.
Wenn der Server strukturierte Informationen benötigt, die nicht im Aufruf enthalten sind – wie ein Datum oder eine Wahl zwischen zwei Optionen – kann er diese über Elicitation anfordern, einen Mechanismus des MCP-Protokolls. Beschränken Sie dies darauf, was der Benutzer vernünftigerweise bereitstellen kann; verwenden Sie es niemals, um Geheimnisse zu sammeln oder die normale Authentifizierung zu umgehen.
Mehrere Konten und Firmwissen
Zwei optionale Kompatibilitäten verbessern die Integration. Um Benutzern zu helfen, die mehrere Konten verbinden, stellen Sie ein Profil-Werkzeug bereit, das authentifiziert, schreibgeschützt und mit _meta["openai/profile"]: true markiert ist. OpenAI verwendet dies, um verbundene Konten zu identifizieren und Benutzern zu helfen, diese voneinander zu unterscheiden. Das Profil wird aus den validierten Anweisungsdaten der Anfrage abgeleitet, und jeder Aufruf bleibt auf diese Anweisungsdaten beschränkt.
Die Funktion Firmwissen von ChatGPT kann die schreibgeschützten Werkzeuge Ihres Servers nutzen. Um ein Plugin als Quelle eligible zu machen, implementieren Sie die standardmäßigen Eingabeschemas für search- und fetch-Werkzeuge, markieren Sie andere schreibgeschützte Werkzeuge mit readOnlyHint: true und geben Sie absolute, vom Benutzer öffnbare URLs für Quellen zurück, die das Modell zitieren muss.
Bereitstellung des Endpunkts
Eine öffentliche Einreichung erfordert einen Server an einer stabilen, öffentlich erreichbaren HTTPS-Adresse. Dieser Endpunkt muss den streamable HTTP-Transport unterstützen, auf einer stabilen URL antworten (typischerweise endend mit /mcp), den Latenz- und Verfügbarkeitsanforderungen Ihrer Workflows gerecht werden, Ihre Dienste und Daten erreichen, Authentifizierungs- und Autorisierungsgrenzen wahren sowie Protokolle und Metriken für Initialisierungs- und Werkzeugaufruf-Fehler erzeugen.
Der Secure MCP Tunnel von OpenAI ermöglicht es Ihnen, einen privaten Server mit ChatGPT zu verbinden, erfüllt aber nicht die Anforderungen für eine öffentliche Einreichung, noch tut dies ein temporärer Tunnel oder eine lokale Adresse. Wenn der Server privat bleiben muss, platzieren Sie einen öffentlichen HTTPS-Proxy vor ihm: mTLS, verwaltet von OpenAI, authentifiziert ChatGPT als Client, OAuth 2.1 authentifiziert Ihre Benutzer, und eine IP-Whitelist – einschließlich von OpenAI veröffentlichter Bereiche für ChatGPT-Verbindungen, die automatisch aktualisiert werden – kann hinzugefügt werden, ersetzt aber niemals die Authentifizierung.
Bevor Sie live gehen: Injizieren Sie Anweisungsdaten über den Secret Manager Ihres Hosts, konfigurieren Sie den Autorisierungsserver und Umleitungen, setzen Sie Timeouts und Rate Limits für teure oder extern sichtbare Werkzeuge, entfernen Sie Debug-Antworten und unnötige personenbezogene Daten und überprüfen Sie, dass Protokolle keine Tokens oder sensiblen Ergebnisse enthalten. Nach der Bereitstellung spielen Sie MCP Inspector gegen die Produktionsadresse ab.
Weiterentwicklung ohne Bruch
Halten Sie veröffentlichte Werkzeugnamen und Schemas rückwärtskompatibel: Fügen Sie Felder oder Werkzeuge hinzu, brechen Sie aber keine bestehenden Verträge. Wenn sich Metadaten ändern, aktualisieren Sie die Verbindung und spielen Sie Ihre Evaluierungssuite ab, bevor Sie einreichen. Für eine Schnittstelle ändern Sie die Ressourcen-ID, wenn sich HTML, JavaScript oder CSS auf eine Weise entwickelt, die einen zwischengespeicherten Komponente brechen könnte.
Sicherheitserinnerungen
- Alle Werkzeugeingaben sind unzuverlässig: Validieren Sie sie und erzwingen Sie Autorisierung auf dem Server
- Erfordern Sie Bestätigung für hochwirksame Schreibvorgänge
- Halten Sie Geheimnisse und sensible Daten aus Metadaten und Ergebnissen fern
- Protokollieren Sie genug, um zu untersuchen, schließen aber Anweisungsdaten und unnötige personenbezogene Daten aus
- Begrenzen Sie teure oder extern sichtbare Aktionen
Kernaussagen
- Ein benannter, versionierter Server mit kurzen, querschnittlichen
instructions - Ein Werkzeug pro Aktion, mit Titel, Intent-Beschreibung, Schemas, Annotationen und Autorisierung im Handler
structuredContentkonform zum Ausgabeschema,isError: truefür Geschäftsfehler, nichts Geheimnisvolles in_meta- Veröffentlichung: stabiler, öffentlicher HTTPS über streamable HTTP; der Secure MCP Tunnel ist unzureichend
- Rückwärtskompatible Verträge und versionierte Ressourcen-IDs