MCP-Tools über HTTP aufrufen

Metapads MCP-Server ist einfach ein HTTP-Endpunkt, der JSON-RPC 2.0 spricht. Interaktive Clients wie Claude Desktop und Claude Code kapseln diesen Transport für Sie, aber Sie können ihn auch direkt aus jedem Skript, jedem curl-Befehl oder jeder CI-Pipeline aufrufen — nützlich, wenn keine interaktive OAuth-Anmeldung möglich ist.

Der Endpunkt

POST /mcp/{model_id}
Authorization: Bearer mpt_your_token_here
Content-Type: application/json

Eine einzige URL bedient jedes MCP-Tool. Welches Tool ausgeführt wird, bestimmt der JSON-RPC-Body, nicht der Pfad.

Der Request-Envelope

Jede Anfrage folgt JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { /* tool-specific */ }
  }
}

method ist für die eigentliche Arbeit fast immer tools/call.
params.name wählt eines der MCP-Tools — dieselben Namen, die Sie in dieser Referenz sehen (get_metamodel, search_nodes, create_nodes usw.).
params.arguments ist das Eingabeschema des Tools — die Parameter jedes Tools finden Sie im jeweiligen APITool-Knoten.

Weitere JSON-RPC-Methoden

Methode	Zweck
`initialize`	Handshake — liefert Protokollversion + Server-Informationen.
`ping`	Statusprüfung.
`tools/list`	Liefert die vollständige Liste der verfügbaren Tools mit ihren JSON-Schemata.
`tools/call`	Ein Tool ausführen.
`notifications/initialized`	Einseitige Benachrichtigung — keine Antwort erwartet.

Praktisches Beispiel: nach Knoten suchen

curl -X POST https://app.metapad.ai/mcp/your-model-id \
  -H "Authorization: Bearer mpt_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_nodes",
      "arguments": { "node_type": "Feature", "limit": 10 }
    }
  }'

Antwort:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"total_count\": 3, \"returned_count\": 3, \"nodes\": [...]}"
      }
    ]
  }
}

Die strukturierte Ausgabe des Tools ist JSON-codiert in result.content[0].text enthalten — parsen Sie sie auf der Client-Seite.

Praktisches Beispiel: einen Knoten erstellen

curl -X POST https://app.metapad.ai/mcp/your-model-id \
  -H "Authorization: Bearer mpt_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_nodes",
      "arguments": {
        "nodes": [{"node_type": "Feature", "label": "OAuth integration"}]
      }
    }
  }'

Mutationen werden über das Kollaborationssystem verteilt — Browser-Nutzer sehen den neuen Knoten in Echtzeit erscheinen.

Fehlerbehandlung

Fehler kommen im JSON-RPC-Fehler-Envelope zurück:

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32602, "message": "..."}}

Code	Bedeutung
`-32700`	Parse-Fehler — der Anfrage-Body war kein gültiges JSON.
`-32600`	Ungültige Anfrage — falsche JSON-RPC-Version, fehlende `method`.
`-32601`	Methode nicht gefunden — unbekannte JSON-RPC-Methode.
`-32602`	Ungültige Parameter — die Tool-Argumente entsprechen nicht dem Schema.
`-32603`	Interner Fehler.

Fehler auf HTTP-Ebene (401, 403, 429) werden als einfache HTTP-Fehler vor der JSON-RPC-Ebene zurückgegeben. Eine 401 enthält einen WWW-Authenticate-Header, der auf die OAuth-Discovery-URL verweist.

REST API v1 vs. MCP HTTP API

Beide verwenden dieselben mpt_...-Tokens. Verwenden Sie, was zu Ihrem Skript passt:

	REST API v1	MCP HTTP API
URL-Form	`/api/v1/models/{id}/nodes`, `/folders`, `/assets`	`/mcp/{id}` (einzelner Endpunkt)
Lese-Form	Konventionelle REST-Ressourcen	JSON-RPC-Tool-Aufrufe
Schreibzugriff	Nur Ressourcen-Upload/-Löschung	Vollständiges Lesen + Schreiben (Knoten, Beziehungen, Typen erstellen/aktualisieren/löschen)
Am besten für	Ein Modell von einem Dashboard aus durchsuchen, auf Änderungen pollen	Automatisierungsskripte, CI-Pipelines, alles, was Mutationen benötigt

Sicherheit

Behandeln Sie mpt_...-Tokens wie Passwörter — committen Sie sie niemals in Repositorys und teilen Sie sie nicht in Chats.
Tokens sind auf ein einzelnes Modell beschränkt.
Widerrufen und rotieren Sie Tokens im Tab „API-Tokens“, wenn sie nicht mehr benötigt werden.