AI-Entwicklung

Wie Claude Code, Codex und andere AI-Coding-Agents MCP-Tools rufen: JSON-RPC, Tool Schema und Rechte (2026)

Ca. 16 Min.

Der Protokolltext hat Schema und Function Calling schon getrennt. Dieser landet nur auf Coding-Agents: das Modell füllt Argumente; der Host sendet JSON-RPC. Verbinden, listen, Schema, dann Rechte sind vier Schritte — nicht der Satz „MCP anschließen“.

Bevor Sie lesen

Schritt Was er schließt Wer ausführt
Config .mcp.json / config.toml stdio oder http; url braucht type
Entdecken tools/list + inputSchema Der Host listet; das Modell sieht die Leitung nicht
Aufruf arguments auf tools/call Modell füllt JSON; Host sendet RPC
Rechte mcp__server__tool / enabled_tools Verbunden ≠ automatisch laufen

MCP ist Host-zu-Server. Das Modell sieht Toolnamen und Parameter-Schema.

Der Host ruft MCP, nicht das Modell

Claude Code, Codex und Cursor sind MCP-Clients. Nach dem Sitzungsstart verbindet der Host, sendet JSON-RPC 2.0 tools/list und reicht jedes inputSchema an das Modell. Das Modell gibt nur Argument-JSON aus. Der Host sendet tools/call und erzeugt Nebenwirkungen. Ohne diesen Sprung ist MCP eine Config-Datei.

  • Config: wie der Server startet. stdio ist ein lokaler Prozess. http ist remote. Beides sind Objekte, keine mündliche Abmachung.
  • Schema: order_id muss durch inputSchema. Ein weites object lädt erfundene Schlüssel ein.
  • Rechte: Claude schreibt mcp__server__tool. Codex nutzt enabled_tools und einen Freigabemodus. Cursor nutzt mcpAllowlist. Ein verbundener Server öffnet diese Türen nicht.

Schema gegen Function Calling auf Protokollebene: MCP Tool Schema vs. Function Calling. Das eigene Tool-JSON eines Coding-Agents: AI-Coding-Agents und JSON-Toolaufrufe. Warum Schema eine Tür ist: Warum AI JSON Schema braucht. Dieser Text definiert die Wörter nicht neu. Er zeigt nur, wie der Host MCP laufen lässt.

Erstes Objekt: Server-Config

Claude Codes Projektdatei ist .mcp.json an der Repo-Wurzel. Sie darf ins Versionsarchiv. Private Einträge liegen in ~/.claude.json. Eine url braucht type: http (streamable-http ist Alias) oder sse / ws. Eine url ohne type gilt als kaputtes stdio und wird übersprungen. Fiktiver Bestelldienst — keine echten Geheimnisse:

{
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "node",
      "args": ["./servers/orders-mcp.js"]
    }
  }
}

Codex schreibt denselben Fakt in ~/.codex/config.toml oder in .codex/config.toml eines vertrauenswürdigen Projekts, unter [mcp_servers.orders]. stdio nutzt command / args. Remote nutzt url. Cursor nutzt .cursor/mcp.json oder die Nutzerdatei; Editor und CLI teilen sie. Ein neuer Projektserver wartet in Claude Code auf Freigabe. Er verbindet nicht von selbst.

Zweites Objekt: tools/list und inputSchema

Nach dem Verbinden fragt der Host, welche Tools existieren. Das ist JSON-RPC, kein HTTP-Aufruf des Modells:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Der Server gibt eine Tabelle zurück. Jede Zeile ist Name, Beschreibung und ein JSON Schema. Die Spezifikation verlangt eine tools-Fähigkeit. Die Liste darf sich mit der Autorisierung ändern. Sie darf nicht pro Verbindung zittern. Der Coding-Agent macht daraus Tools für das Modell. In Claude Code heißt der Aufruf mcp__orders__lookup_order. Ein Plugin-Server bettet auch den Plugin-Namen ein. Ist die Tabelle groß, verschieben offizielle Clients Tools und holen sie per Suche. Die ganze Tabelle nicht standardmäßig in den Kontext kippen.

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Drittes Objekt: das Modell füllt, der Host tools/call

Das Modell sieht den Namen, den der Host veröffentlicht hat. In einer Claude-Code-Sitzung sieht ein Aufruf so aus:

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "mcp__orders__lookup_order",
  "input": { "order_id": "A-1042" }
}

Der Host prüft input gegen inputSchema und übersetzt in das RPC an den Server. Der Drahtname ist das registrierte lookup_order, ohne mcp__-Präfix:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lookup_order",
    "arguments": { "order_id": "A-1042" }
  }
}

Bei Erfolg content zurück. Bei Fehler isError setzen und den Grund als Objekt schreiben. Keinen Prosasatz fallen lassen. Das Modell liest das Zurückschreiben, nicht den Socket.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}" }
    ],
    "isError": false
  }
}

Viertes Objekt: Ausführungsrechte

Die MCP-Spezifikation sagt: ein Tool-Aufruf soll ablehnbar sein. Coding-Agents schreiben die Ablehnung als Regeln, nicht als Prompt. Claude Code nutzt den vollen Aufrufnamen:

{
  "permissions": {
    "allow": ["mcp__orders__lookup_order"],
    "ask": ["mcp__orders__create_note"],
    "deny": ["mcp__orders__refund_order"]
  }
}

Offizielle Reihenfolge bleibt deny, ask, allow. Ein nacktes mcp__*-deny nimmt MCP aus dem Kontext. Codex nutzt enabled_tools als Allow-Liste, disabled_tools als spätere Deny-Liste und auto / prompt / approve als Default, überschreibbar pro Tool. Cursor fragt standardmäßig; mcpAllowlist in permissions.json heißt orders:lookup_order. Die Türen Shell / Git / Dateisystem: Coding-Agent-Rechtemodell. MCP ist eine vierte Tabelle, kein Ersatz für die drei.

Fünf Schritte zu einem ausführbaren MCP

Nicht bei „bitte MCP anschließen“ starten. Objekte schreiben:

  1. Zuerst die Server-Config. stdio oder http. type an jede url. Geheimnisse in Umgebungsvariablen, nicht ins Repo.
  2. tools/list selbst laufen lassen. Namen und required notieren. Ein Tool ohne Schema geht nicht an das Modell.
  3. inputSchema festziehen. pattern, enum, additionalProperties: false. Eine Abfrage darf keinen Refund-Schlüssel wachsen.
  4. Rechte pro Tool schreiben. Nur-Lese-Lookup auf allow. Schreiben auf ask. Refund auf deny. Codex: zuerst mit enabled_tools schneiden.
  5. Drei JSON-Spuren eines Erfolgs behalten: tool_use, tools/call, result. Passen sie, ist der Sprung echt.

Wie Schema zur Tür wird: Agents API + JSON Schema. Dieser Text verlangt nur, dass jeder MCP-Schritt auf einem Coding-Agent ein Objekt ist, das der Host sendet.

Eine MCP-Abweichung prüfen: drei JSON-Spuren ausbreiten

Ein Fehlschlag ist meist Name, Schema oder Rechte — kein Modell, das „MCP nicht kann“.

  • inputSchema neben arguments formatieren. Fehlende Felder und Extra-Schlüssel suchen.
  • Mit JSONPath extrahieren $.params.name und $.input.order_id ziehen.
  • Einen Durchlass und eine Ablehnung JSON Diff. Zuerst Regel und Schema, dann den Prompt.
  • Host-Name mcp__orders__lookup_order gegen RPC-Name lookup_order prüfen. Plugin-Server brauchen ein Plugin-Segment.
  • Keine Config, Token oder Sitzungslogs in einen öffentlichen Formatter. JSONSort läuft lokal im Browser.

Lassen sich die drei Spuren gegen Schema neu aufbauen, haben Sie MCP gesammelt. Sonst nur „ich habe Verbinden geklickt“.

Häufige Fallen

  • Verbinden für Rufen halten. Verbinden heißt nur: Prozess oder HTTP steht. Ohne list, Schema und Rechte kann das Modell noch nicht rufen.
  • MCP für Function Calling halten. Für das Modell ist beides JSON füllen. Für den Host kommt bei MCP ein JSON-RPC-Sprung dazu. Der Protokolltext hat die Wörter getrennt. Hier müssen Sie den Sprung nur sehen.
  • url ohne type. Claude Code überspringt sie als kaputtes stdio. Der Remote-Server verschwindet.
  • Einen Server konfigurieren und Tools nie schneiden. Eine große Tabelle landet im Kontext. Offizielle Verzögerung und enabled_tools existieren deshalb.
  • „Alle MCP automatisch freigeben“ als Default. Cursors Alles-Freigabe, Claude-Bypass und Codex-überall-auto sind für isolierte Umgebungen. Alltag schreibt pro Tool.
  • Projekt-.mcp.json für eine private Datei halten. Sie liegt im Versionsarchiv. Kollegen sehen eine ausstehende Freigabe. Geheimnisse bleiben nutzerskopiert.

FAQ

Sendet der Coding-Agent selbst JSON-RPC?

Nein. Das Modell füllt Toolname und arguments. Der Host baut id, method und params. Steht tools/call im Log, ist das der Client, nicht das Modell.

Welche Tür zuerst: inputSchema oder Rechte?

Zuerst Form, dann Ausführung. Fällt Schema, kein RPC. Passiert Schema, können ask oder deny noch greifen. Die Türen schließen anderes.

stdio oder http?

Lokale Dateien oder ein lokaler Prozess: stdio. Ein gehosteter Dienst: http. Claude Code bevorzugt http für Remote; SSE ist veraltet. WebSocket passt, wenn der Server Ereignisse schiebt.

Zu viele Tools?

Claude Code kann MCP-Tools verzögern und per Suche ausklappen. Codex schneidet mit enabled_tools. Nicht fünfzig Tools in eine Sitzung kippen.

Kann ein Subagent diese MCP-Tools nutzen?

Es hängt vom Produkt ab. Claude-Code-Rechte und allowed-tools brauchen den vollen Aufrufnamen. Agents-API-Subagents erben MCP, nicht Ihre function-Tools. Nicht annehmen, eine Tabelle kopiere sich in jede Kind-Sitzung.

Schluss

Ein Coding-Agent, der MCP ruft, ist kein Modell, das den Server trifft. Der Host listet, das Modell füllt JSON, der Host dann tools/call. Schema und Rechte sind zwei Türen.

Schreiben Sie, welchen Toolnamen, welches Schema und welche Regel A-1042 nähme. Können Sie auf drei Objekte zeigen, ist MCP verbunden. Modelle wechseln. Diese drei sollten zuerst stehen.

Weiterlesen

Änderungsprotokoll: Erstveröffentlichung