JSON-RPC 2.0 Protokoll

Der CODEFLUSS MCP Server implementiert das Model Context Protocol (MCP) basierend auf JSON-RPC 2.0. Diese Seite beschreibt das Protokollformat und alle verfügbaren Methods.

JSON-RPC 2.0 Grundlagen

Jede Anfrage an den MCP Server muss dem JSON-RPC 2.0 Standard entsprechen.

Request-Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {}
}

Feld	Typ	Beschreibung
`jsonrpc`	string	Muss immer `"2.0"` sein
`id`	number \| string	Eindeutige Request-ID für die Zuordnung der Response
`method`	string	Name der aufzurufenden Methode
`params`	object	Parameter für die Methode (optional)

Response-Format (Erfolg)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [...]
  }
}

Response-Format (Fehler)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {}
  }
}

Verfügbare Methods

initialize

Initialisiert die MCP-Verbindung und tauscht Capabilities aus.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {},
      "resources": {}
    },
    "serverInfo": {
      "name": "codefluss-mcp-server",
      "version": "1.0.0"
    }
  }
}

tools/list

Listet alle verfügbaren Tools auf.

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "list_projects",
        "description": "Listet alle Projekte des Benutzers auf",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "get_project",
        "description": "Ruft Details eines spezifischen Projekts ab",
        "inputSchema": {
          "type": "object",
          "properties": {
            "projectId": {
              "type": "string",
              "description": "Die eindeutige Projekt-ID"
            }
          },
          "required": ["projectId"]
        }
      }
    ]
  }
}

tools/call

Ruft ein spezifisches Tool auf.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": \"proj_abc123\", \"name\": \"Meine Website\"}]"
      }
    ],
    "isError": false
  }
}

resources/list

Listet verfügbare Ressourcen auf.

Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resources": [
      {
        "uri": "codefluss://projects",
        "name": "Projects",
        "description": "Alle Projekte des Benutzers",
        "mimeType": "application/json"
      },
      {
        "uri": "codefluss://design-system/{projectId}",
        "name": "Design System",
        "description": "Design Tokens eines Projekts",
        "mimeType": "application/json"
      }
    ]
  }
}

resources/read

Liest eine spezifische Ressource.

Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "codefluss://projects"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "contents": [
      {
        "uri": "codefluss://projects",
        "mimeType": "application/json",
        "text": "[{\"id\": \"proj_abc123\", \"name\": \"Meine Website\"}]"
      }
    ]
  }
}

Error Codes

Der CODEFLUSS MCP Server verwendet standardmäßige JSON-RPC 2.0 Error Codes sowie benutzerdefinierte Codes.

Standard JSON-RPC 2.0 Errors

Code	Name	Beschreibung
`-32700`	Parse error	Ungültiges JSON
`-32600`	Invalid Request	Request-Objekt ist ungültig
`-32601`	Method not found	Methode existiert nicht
`-32602`	Invalid params	Ungültige Methodenparameter
`-32603`	Internal error	Interner Server-Fehler

CODEFLUSS-spezifische Errors

Code	Name	Beschreibung
`-32001`	Authentication failed	Ungültiger oder fehlender API-Key
`-32002`	Authorization failed	Keine Berechtigung für diese Aktion
`-32003`	Resource not found	Projekt/Block/Asset nicht gefunden
`-32004`	Validation error	Eingabedaten sind ungültig
`-32000`	Rate limit exceeded	Zu viele Anfragen

Fehler-Beispiele

Parse Error:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "data": {
      "detail": "Unexpected token at position 42"
    }
  }
}

Invalid Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "detail": "Missing required field: method"
    }
  }
}

Method not found:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "method": "unknown_method"
    }
  }
}

Invalid params:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "projectId",
      "error": "Required field missing"
    }
  }
}

Authentication failed:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Authentication failed",
    "data": {
      "reason": "Invalid or missing API key"
    }
  }
}

HTTP-Spezifika

Endpoint

POST https://app.codefluss.io/api/mcp

Headers

Content-Type: application/json
Authorization: Bearer cf_live_sk_...

HTTP Status Codes

Der MCP Server antwortet immer mit HTTP 200, auch bei JSON-RPC Errors. Der tatsächliche Erfolg/Fehler wird im Response-Body kommuniziert.

HTTP Status	Bedeutung
`200`	Request verarbeitet (prüfe Response-Body)
`401`	Kein Authorization Header
`405`	Nur POST erlaubt
`429`	Rate Limit überschritten
`500`	Server-Fehler

Batch Requests

JSON-RPC 2.0 unterstützt Batch Requests. Sende ein Array von Requests:

Request:

[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_projects",
      "arguments": {}
    }
  }
]

Response:

[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "tools": [...]
    }
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
      "content": [...]
    }
  }
]

Notifications

Notifications sind Requests ohne id. Sie erhalten keine Response:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}

TypeScript Types

interface JsonRpcRequest {
  jsonrpc: '2.0';
  id: number | string;
  method: string;
  params?: Record<string, unknown>;
}

interface JsonRpcSuccessResponse {
  jsonrpc: '2.0';
  id: number | string;
  result: unknown;
}

interface JsonRpcErrorResponse {
  jsonrpc: '2.0';
  id: number | string | null;
  error: {
    code: number;
    message: string;
    data?: unknown;
  };
}

type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;

Nächste Schritte

Einführung - Überblick über den MCP Server
Schnellstart - Erste Schritte
Authentifizierung - API-Keys und Session-Auth