Regeln der Umwandlung

Diese Seite beschreibt genau, was das Werkzeug aus deiner Spezifikation macht. Stand der Regeln: MCP-Spezifikation 2025-11-25, geprüft am 08.11.2026.

Operation wird Tool

Jede Kombination aus Pfad und HTTP-Methode unter paths wird genau ein Tool. Ein MCP-Tool besteht laut Spezifikation aus name, optional title, description, inputSchema (ein JSON-Schema-Objekt), optional outputSchema und annotations.

OpenAPI	MCP-Tool
`operationId` (sonst Methode + Pfad)	`name`
`summary`	`title` (wenn höchstens 80 Zeichen)
`summary` + `description`	`description`
Parameter und Request-Body	`inputSchema`
erste 2xx-Antwort mit JSON-Objekt	`outputSchema` (optional)
HTTP-Methode	`annotations` (optional)

Hat eine Operation keine Parameter, wird das von der MCP-Spezifikation empfohlene Schema {"type": "object", "additionalProperties": false} gesetzt.

Tool-Namen und Grenzen

Ohne operationId entsteht der Name aus Methode und Pfad, Pfadparameter werden zu by_…: GET /users/{id}/orders wird get_users_by_id_orders. Wahlweise wird der Name in snake_case oder camelCase umgeschrieben und mit einem Präfix versehen. Doppelte Namen bekommen eine Endung _2, _3 …; zu lange Namen werden gekürzt und mit einer kurzen Prüfsumme eindeutig gemacht.

Wo	Erlaubte Zeichen	Länge
MCP-Spezifikation (Empfehlung, „SHOULD“)	A–Z, a–z, 0–9, `_`, `-`, `.`	1–128
Anthropic Messages API	A–Z, a–z, 0–9, `_`, `-`	1–128
OpenAI Function Calling	A–Z, a–z, 0–9, `_`, `-`	höchstens 64

Darum ist die Voreinstellung 64 Zeichen ohne Punkt: Solche Namen funktionieren überall. Ein Punkt (z. B. aus operationId: users.list) bleibt in der Schreibweise „wie operationId“ erhalten und wird als Warnung markiert. Manche Clients setzen zusätzlich den Servernamen vor den Tool-Namen; die Einstellung „48 Zeichen“ lässt dafür Platz.

Parameter und Request-Body

Pfad, Query, Header, Cookie: Jeder Parameter wird ein Argument mit seinem Schema und seiner Beschreibung. Pfadparameter sind immer Pflicht. Parameter am Pfad und an der Operation werden zusammengeführt; die Operation gewinnt.
Header Accept, Content-Type, Authorization werden nicht als Argumente angeboten – die setzt der Server.
Argumentnamen enthalten nur Buchstaben, Ziffern, _, . und -: aus filter[status] wird filter_status. Kollidieren zwei Namen, bekommt der zweite den Ort als Präfix (z. B. query_id).
Request-Body: Ist er ein Objekt (auch über allOf zusammengesetzt) und kollidiert kein Feld mit einem Parameter, werden seine Felder direkt Argumente. Sonst – oder mit der Einstellung „als ein Argument“ – gibt es ein Argument body.
Inhaltstyp: bevorzugt application/json, dann +json, Formulare, Multipart, Text. Datei-Uploads werden markiert, weil ein Tool-Argument nur Text bzw. JSON transportiert.
Swagger 2.0: in: body wird der Body, in: formData wird ein Formular-Body.

Schemas, $ref und nullable

$ref auf Stellen in derselben Datei werden eingebettet, damit jedes Tool für sich verständlich ist. Rekursive Schemas werden nach einer Ebene abgeschnitten und markiert. Verweise auf andere Dateien oder URLs werden nicht geladen (die Daten bleiben im Browser) und durch einen Platzhalter ersetzt.
OpenAPI 3.0: nullable: true wird zu "type": ["…", "null"], example zu examples, boolesches exclusiveMinimum/exclusiveMaximum zur Zahlform von JSON Schema 2020-12 – dem Dialekt, den MCP ohne $schema annimmt.
readOnly-Felder fehlen im inputSchema (sie kommen nur in Antworten vor), writeOnly-Felder fehlen im outputSchema.
x-…-Erweiterungen, discriminator, xml und externalDocs werden entfernt.

Hinweise (annotations)

MCP kennt die Hinweise readOnlyHint, destructiveHint, idempotentHint und openWorldHint. Es sind ausdrücklich nur Hinweise; Clients sollen sie bei nicht vertrauenswürdigen Servern nicht als Zusicherung behandeln. Das Werkzeug leitet sie aus der HTTP-Semantik ab:

Methode	Gesetzte Hinweise
GET, HEAD, OPTIONS	`readOnlyHint: true`
PUT	`readOnlyHint: false`, `idempotentHint: true`
DELETE	`readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: true`
POST, PATCH	`readOnlyHint: false` (destructiveHint bleibt beim Standardwert true)

Ob eine API sich an diese Semantik hält, kann das Werkzeug nicht wissen – prüfe die Hinweise vor dem Einsatz.

outputSchema

Auf Wunsch wird das Schema der ersten 2xx-Antwort mit JSON-Inhalt übernommen. Die MCP-Spezifikation verlangt für outputSchema ein Objekt an der Wurzel; Antworten, die Listen oder einfache Werte sind, bekommen deshalb kein outputSchema. Ist es gesetzt, sollte der Server ein passendes structuredContent liefern – das Server-Gerüst tut das für JSON-Objekte.

Was nicht abgebildet wird

Webhooks und Callbacks (sie sind Aufrufe der API an dich, keine Werkzeuge).
Externe $ref-Dateien; führe sie vorher mit einem Bundler zusammen.
OAuth-Abläufe: Das Server-Gerüst erwartet ein fertiges Token in einer Umgebungsvariable.