> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Management-API-MCP

> KI-Clients (Cursor, Claude Desktop, ...) über MCP mit der Management API verbinden

# Management-API-MCP

Die Management API bietet einen [MCP](https://modelcontextprotocol.io)-Endpoint (Model
Context Protocol), damit KI-Clients — Cursor, Claude Desktop und andere MCP-kompatible Tools —
direkt auf die Daten Ihrer Organisation lesend und schreibend zugreifen können, ohne eine
individuelle Integration. Es ist dieselbe Management API, die Sie bereits über REST nutzen:
MCP ist ein zusätzlicher Transportweg auf demselben Dienst und stellt eine kuratierte
**Allowlist** von Tools bereit statt jeder REST-Route.

> [!NOTE]
>
> MCP ist additiv. Ihre bestehenden API-Schlüssel-Integrationen, Webhooks und REST-Aufrufe
> bleiben davon vollständig unberührt — diese Seite betrifft nur das Verbinden eines
> KI-Clients.

## Verbinden

```
https://api.rxscale.com/v1/management/mcp
```

Fügen Sie diese URL zur Server-Konfiguration Ihres MCP-Clients hinzu. Cursor unterstützt zum
Beispiel [statische OAuth-Client-Anmeldedaten](https://cursor.com/docs/mcp) für einen
entfernten Server mit einer eigenen, fest zugewiesenen Client-ID statt Dynamic Client
Registration -- genau so ist dieser Endpoint eingerichtet. RxScale stellt eine
Auth0-Anwendung für Ihre Organisation bereit und gibt Ihnen deren Client-ID; tragen Sie diese
im `auth`-Block von `mcp.json` ein statt eines Bearer-Tokens:

```json theme={null}
{
  "mcpServers": {
    "rxscale-management": {
      "url": "https://api.rxscale.com/v1/management/mcp",
      "auth": {
        "CLIENT_ID": "${env:RXSCALE_MCP_CLIENT_ID}",
        "scopes": ["order:read", "product:read", "questionnaire:read"]
      }
    }
  }
}
```

Setzen Sie `RXSCALE_MCP_CLIENT_ID` in Ihrer Shell-Umgebung, statt die Client-ID wörtlich in
die Datei zu schreiben -- Cursor interpoliert `${env:...}` im `auth`-Block genauso wie in
`headers`. Setzen Sie `scopes` immer explizit auf die Liste der Berechtigungs-Strings (siehe
[Berechtigungen](/de/permissions#management-api)), die Ihr RxScale-Kundenbetreuer für Ihren
Client bestätigt hat -- fordern Sie nur an, was Ihre Nutzung des Clients tatsächlich braucht.

> [!WARNING]
>
> Lassen Sie `scopes` nicht weg, um "alles zu bekommen". Cursors dokumentiertes Fallback für
> ein weggelassenes `scopes`-Feld ist, `scopes_supported` aus den eigenen Metadaten des
> Auth0-Tenants unter `/.well-known/oauth-authorization-server` zu ermitteln -- der
> tenant-weiten Liste des Autorisierungsservers, nicht einer auf diese MCP-Ressource
> beschränkten Liste (der Auth0-Tenant von RxScale hostet auch Scopes anderer APIs). Cursor
> leitet keine API-spezifischen Berechtigungen aus den RFC-9728-Metadaten dieser Ressource
> oder aus den Auth0-AS-Metadaten ab; der einzig verlässliche Weg, genau die Berechtigungen
> zu erhalten, die Ihr Client haben soll, ist, sie explizit in `scopes` aufzulisten.

> [!NOTE]
>
> Dynamic Client Registration ist für diesen Rollout nicht aktiviert -- die Client-ID oben
> ist eine, die RxScale Ihrer Organisation zuweist, nicht eine, die Cursor spontan
> registriert. Bevor die Anmeldung
> überhaupt funktionieren kann, müssen zwei Dinge außerhalb dieser Konfiguration existieren:
> Fragen Sie Ihren RxScale-Kundenbetreuer nach einer Client-ID, und lassen Sie ihn Cursors
> feste OAuth-Redirect-URL(s) dagegen in Auth0 freischalten -- Cursor dokumentiert feste
> Callback-URLs pro Oberfläche, nicht eine einzige:
>
> * Web und Cursor Agents: `https://www.cursor.com/agents/mcp/oauth/callback`
> * Desktop-App: `http://localhost:8787/callback`
>
> Schalten Sie beide frei, wenn sich die Nutzer Ihrer Organisation sowohl über die
> Web-/Agents-Oberfläche als auch über die Desktop-App anmelden; andernfalls nur die, die Sie
> verwenden. Die Anmeldung schlägt mit einer Redirect-URI-Abweichung fehl, bis die Client-ID
> bereitgestellt und die benötigte(n) Redirect-URL(s) registriert sind. Erst wenn beides
> existiert, fordert die Verbindung Sie auf, sich über die Auth0-Anmeldeseite Ihrer
> Organisation anzumelden -- es gibt weiterhin keinen API-Schlüssel oder Client-Secret, den
> Sie in die Konfigurationsdatei einfügen müssten, aber es gibt eine Einrichtung außerhalb
> dieser Datei, die RxScale zuerst erledigen muss.

> [!TIP]
>
> Wenn Ihr Client für OAuth nur einen statischen Header statt eines `auth`-Blocks
> unterstützt -- oder Sie ein nicht-interaktives Token für ein Skript möchten -- fordern Sie
> selbst eines mit dem untenstehenden Client-Credentials-Grant an und referenzieren Sie es
> genauso, wie Cursors `headers`-Feld Umgebungsinterpolation unterstützt:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "rxscale-management": {
>       "url": "https://api.rxscale.com/v1/management/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:RXSCALE_MCP_TOKEN}"
>       }
>     }
>   }
> }
> ```

## Authentifizierung

Der MCP-Endpoint akzeptiert dieselben Anmeldeinformationen wie der Rest der Management API —
siehe [Authentifizierung](/de/authentication#management-api-api-schlüssel-oder-oauth-bearer-token)
für alle Details — mit einem wichtigen Unterschied: **seine Bearer-Tokens werden für eine
eigene OAuth-Audience ausgestellt, getrennt von der REST-API.**

| | Audience |
| - | - |
| REST (`/v1/management/*`) | `https://api.rxscale.com/v1/management` |
| MCP (`/v1/management/mcp`) | `https://api.rxscale.com/v1/management/mcp` |

Ein für eine Audience ausgestelltes Token wird bei der jeweils anderen abgelehnt. Um ein Token
für die MCP-Audience anzufordern, wird derselbe OAuth-2.0-Client-Credentials-Grant verwendet,
der in [Authentifizierung](/de/authentication#ein-bearer-token-erhalten) beschrieben ist, mit
`audience` gesetzt auf die eigene URL des MCP-Endpoints:

```bash theme={null}
curl -X POST "https://YOUR_AUTH0_DOMAIN/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "audience": "https://api.rxscale.com/v1/management/mcp",
    "grant_type": "client_credentials",
    "scope": "order:read product:read"
  }'
```

`scope` ist eine durch Leerzeichen getrennte Liste derselben Berechtigungs-Strings, die auch
bei REST verwendet werden (siehe [Berechtigungen](/de/permissions#management-api)) --
fordern Sie nur an, was der aufrufende Client benötigt; die Tools des resultierenden Tokens
sind darauf beschränkt, genau wie bei den Berechtigungen eines API-Schlüssels.

> [!WARNING]
>
> Das Token einer Machine-to-Machine-Anwendung trägt `sub` = `<client_id>@clients`, und
> RxScale muss diesen `sub` als Service-Principal in Ihrer Organisation registrieren,
> bevor damit Aufrufe möglich sind — Scopes allein genügen nicht. Bis dahin antwortet der
> Endpoint mit `401` und `{"code": "user_not_found"}`. Siehe
> [Ein Bearer-Token erhalten](/de/authentication#ein-bearer-token-erhalten).

> [!TIP]
>
> Für einen interaktiven KI-Client (Cursor, Claude Desktop) müssen Sie diese Anfrage in der
> Regel nicht selbst stellen. Der Client ermittelt den erforderlichen Auth0-Autorisierungsserver
> über die Metadaten des MCP-Endpoints und führt Sie durch die Anmeldung mit der von RxScale
> bereitgestellten Auth0-Anwendung. Verwenden Sie den obigen Client-Credentials-Grant nur für
> einen eigenen oder headless-Client, der keine OAuth-Discovery implementiert — setzen Sie das
> resultierende `access_token` als `Authorization: Bearer`-Header (oder das Äquivalent in Ihrem
> Client für benutzerdefinierte Header).

API-Schlüssel (`X-API-Key`) funktionieren ebenfalls am MCP-Endpoint, mit denselben
Berechtigungen wie bei REST — nützlich für einen Client, der nur eine statische
Anmeldeinformation unterstützt.

### Client-Kompatibilität (OAuth-Discovery)

Eine nicht authentifizierte Anfrage an den MCP-Endpoint liefert `401` mit einem
`WWW-Authenticate`-Header, der auf das [RFC-9728](https://www.rfc-editor.org/rfc/rfc9728)-Dokument
„Protected Resource Metadata" dieser Ressource verweist:

```
GET /.well-known/oauth-protected-resource/v1/management/mcp
```

```json theme={null}
{
  "resource": "https://api.rxscale.com/v1/management/mcp",
  "authorization_servers": ["https://auth.rxscale.com/"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "doctor:read",
    "doctor_statistics:read",
    "listing_request:read",
    "order:read",
    "patient:read",
    "prescription:read",
    "product:read",
    "product:write",
    "questionnaire:read",
    "questionnaire:write",
    "review_link:read",
    "scheduling:read",
    "statistics:read",
    "wallet_pass:read",
    "wallet_pass_template:read"
  ]
}
```

Strikte RFC-9728-Clients (zum Beispiel die MCP-Unterstützung von VS Code) verlangen, dass das
`resource`-Feld des Metadaten-Dokuments exakt der kanonischen URL des MCP-Endpoints selbst
entspricht — nicht der breiteren Management-API-Wurzel. Deshalb ist die MCP-Audience oben die
`/mcp`-URL und nicht `https://api.rxscale.com/v1/management`. Dieser Discovery-Ablauf bringt
einen Client nur bis zu dem Punkt, den Autorisierungsserver zu finden und die Anmeldung zu
starten; er hebt die oben unter [Verbinden](#verbinden) beschriebene Voraussetzung nicht auf
\-- RxScale muss weiterhin die Client-ID Ihrer Organisation bereitstellen und die exakte(n)
Redirect-URL(s) Ihres Clients in Auth0 registrieren, bevor diese Anmeldung gelingen kann.

### Browser-basierte Clients und Origin-Freischaltung

Eine Anfrage mit einem `Origin`-Header — den nur Browser senden — wird gegen die Allowlist
dieses Dienstes geprüft, **bevor** die Authentifizierung läuft. Ein Origin, der nicht auf der
Allowlist steht, wird sofort abgelehnt, mit `403` und ohne Versuch, Anmeldeinformationen zu
lesen:

```json theme={null}
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Origin is not allowed"}}
```

Jeder Nicht-Browser-MCP-Client — Cursor, Claude Desktop, ein Skript mit `curl` oder einer
HTTP-Bibliothek — sendet niemals einen `Origin`-Header und ist von dieser Prüfung völlig
unberührt; sie existiert, um zu verhindern, dass eine Webseite diesen Endpoint über die
Cookies Ihres Browsers per DNS-Rebinding ansteuert -- ein Angriff, der für einen
Nicht-Browser-Aufrufer irrelevant ist. Relevant ist dies nur, wenn Sie einen **eigenen,
browser-basierten** MCP-Client bauen -- eine Web-App, die diesen Endpoint direkt aus
JavaScript in einer Seite heraus aufruft. Kontaktieren Sie in diesem Fall Ihren
RxScale-Kundenbetreuer mit dem genauen Origin (`scheme://host[:port]`, z.B.
`https://app.example.com`), den Sie freigeschaltet haben möchten; er kann nicht vom Client
selbst hinzugefügt werden, und es gibt keine Selbstbedienungsmöglichkeit, einen zu
registrieren.

## Verfügbare Tools

`tools/list` liefert stets nur die Tools, die die Berechtigungen Ihres Tokens erlauben —
dieselben `EnumAPIKeyPermission`-Scopes, die auch bei REST geprüft werden. Jedes Tool ruft
denselben Handler- und Serialisierungspfad wie sein REST-Äquivalent auf, sodass die beiden
Oberflächen für dieselben Daten nicht unterschiedliches JSON liefern können.

| Tool | REST-Äquivalent | Erforderliche Berechtigung |
| - | - | - |
| `health_check` | `GET /health` | *(jede gültige Anmeldeinformation)* |
| `list_orders` | `GET /orders` | `order:read` |
| `get_order` | `GET /orders/{order_uid}` | `order:read` |
| `get_prescription` | `GET /prescriptions/{prescription_uid}` | `prescription:read` |
| `list_products` | `GET /products` | `product:read` |
| `get_product` | `GET /products/{product_uid}` | `product:read` |
| `create_product` | `POST /products` | `product:write` |
| `update_product` | `PATCH /products/{product_uid}` | `product:write` |
| `list_doctors` | `GET /doctors` | `doctor:read` |
| `get_doctor_statistics` | `GET /doctors/{doctor_uid}/statistics` | `doctor_statistics:read` |
| `list_doctors_statistics` | `GET /statistics/doctors` | `statistics:read` |
| `get_dashboard_statistics` | `GET /statistics/dashboard` | `statistics:read` |
| `list_questionnaires` | `GET /questionnaires` | `questionnaire:read` |
| `get_questionnaire` | `GET /questionnaires/{questionnaire_uid}` | `questionnaire:read` |
| `create_questionnaire` | `POST /questionnaires` | `questionnaire:write` |
| `update_questionnaire` | `PATCH /questionnaires/{questionnaire_uid}` | `questionnaire:write` |
| `update_questionnaire_model` | `PATCH /questionnaires/{questionnaire_uid}/model` | `questionnaire:write` |
| `get_questionnaire_submission_statistics` | `GET /questionnaires/{questionnaire_uid}/statistics/submissions` | `statistics:read` |
| `find_patient` | `GET /patients?email=` | `patient:read` |
| `get_patient` | `GET /patients/{patient_uid}` | `patient:read` |
| `list_appointments` | `GET /scheduling/appointments` | `scheduling:read` |
| `list_appointment_types` | `GET /scheduling/appointment-types` | `scheduling:read` |
| `list_listing_requests` | `GET /listing-requests` | `listing_request:read` |
| `get_listing_request` | `GET /listing-requests/{uid}` | `listing_request:read` |
| `list_wallet_pass_templates` | `GET /wallet-passes/templates` | `wallet_pass_template:read` |
| `list_wallet_passes` | `GET /wallet-passes` | `wallet_pass:read` |
| `list_review_links` | `GET /review-links` | `review_link:read` |

> [!WARNING]
>
> `get_questionnaire_submission_statistics` erfordert `statistics:read`, **nicht**
> `questionnaire:read` — es umschließt einen Statistik-Endpoint und ist daher genauso
> abgesichert wie dessen REST-Route, auch wenn es thematisch bei den anderen
> Fragebogen-Tools eingeordnet ist.

> [!NOTE]
>
> `health_check` erfordert weiterhin **irgendeine** gültige Anmeldeinformation -- einen
> API-Schlüssel oder ein Bearer-Token, das **speziell für die MCP-Audience** ausgestellt
> wurde -- auch wenn keine Berechtigung nötig ist. Ein für die REST-Audience ausgestelltes
> Bearer-Token wird hier genauso abgelehnt wie bei jedem anderen Tool, da die MCP-Route gegen
> `MCP_API_AUDIENCE` prüft, nicht gegen die REST-`API_AUDIENCE` (siehe
> [Authentifizierung](#authentifizierung) oben). Das unterscheidet sich vom REST-Endpoint
> `GET /health`, der überhaupt keine Authentifizierung erfordert: Jeder MCP-Aufruf,
> einschließlich `health_check`, durchläuft zunächst die eigene Authentifizierung dieses
> Endpoints, während `/health` bewusst offen bleibt, damit Infrastruktur ihn
> unauthentifiziert prüfen kann.

### Nicht über MCP verfügbar

Nur die oben aufgeführten Tools existieren. Es gibt kein generisches „beliebigen REST-Endpoint
aufrufen"-Tool, und das Hinzufügen eines neuen Tools ist eine bewusste Katalog-Änderung auf
Seiten von RxScale — ein Tool erscheint nie nur, weil eine REST-Route existiert.

**Ausschließlich über REST verfügbare Management-API-Operationen.** Diese Endpoints
existieren und verhalten sich genau wie auf ihren eigenen REST-Referenzseiten dokumentiert;
sie stehen in der aktuellen Version schlicht nicht auf der MCP-Allowlist:

* **Order Intake und Fulfillment** — Bestellung erstellen, Bestellung aktualisieren,
  Fulfillment erstellen und Fulfillment abbrechen
  ([Order Intake](/de/api-reference/management/order-intake))
* **Rezeptsignierung** — Rezept-PDF rendern oder ein Rezept als extern signiert markieren
* **Benachrichtigungs-Abonnements (Webhooks)** — die gesamte
  `/notification-subscriptions/`-Ressource: Auflisten, Erstellen, Entfernen und
  Test-Versand ([Webhooks](/de/api-reference/management/webhooks))
* **Warteraum** — Registrieren, Statusabfrage oder Stornieren eines Warteraum-Eintrags
  ([Warteraum](/de/api-reference/management/waiting-room))
* **Listing-Request-Entscheidungen** — Annehmen oder Ablehnen eines offenen Listing-Requests
  (Auflisten und Abrufen eines Listing-Requests *sind* über MCP verfügbar; nur die
  Annehmen-/Ablehnen-Aktionen sind ausschließlich über REST)
* **Wallet-Pass-Verifizierung und Push-Benachrichtigungen** (Auflisten von Vorlagen und
  Pässen *ist* über MCP verfügbar)
* **Löschen eines Patientenprofilfeld-Werts**
* **Patienten-Intent-Status** — `GET /patients/{patient_uid}/intent/{intent}` (Auflisten und
  Abrufen eines Patienten per UID oder E-Mail *sind* über MCP verfügbar; dieser engere
  Abruf ist ausschließlich über REST verfügbar)
* **Erstellen und Widerrufen von Review-Links** — `POST /review-links` und
  `DELETE /review-links/{review_link_uid}` (Auflisten von Review-Links *ist* über MCP
  verfügbar)
* **Blacklist von Apotheken-SKUs pro Arzt** — die gesamte
  `/doctors/{uid}/blacklisted-skus`-Ressource
* **Schreibende Terminverwaltungs-Operationen** — Termin stornieren sowie sämtliches CRUD
  für Termintypen und Arzt-Verfügbarkeitsregeln/-ausnahmen (nur das Auflisten von Terminen
  und Termintypen ist über MCP verfügbar)

**Über die Management API überhaupt nicht verfügbar — weder über REST noch daher über MCP.**
Das sind keine fehlenden MCP-Tools; die zugrunde liegende Fähigkeit wird von dieser API für
keinen Client heute angeboten, weshalb es auch keine REST-Seite dazu gibt:

* Löschen eines Produkts oder eines Fragebogens
* Fragebogen-Autorenfunktionen (individuelles CSS, Datei-Assets, Archivierung,
  Duplizierung) — ausschließlich im Admin Tool
* Verschachtelte SKU-Attributgraphen über die auf
  [Produkte](/de/api-reference/management/products) dokumentierte Create/Patch-Form hinaus
* CSV-Exporte von Statistiken
* Referral-Scan- und Referral-Konversionsstatistiken

Verwenden Sie die [Management-API-REST-Referenz](/de/api-reference/management/overview) für
die erste Gruppe von Operationen.

## Ein Tool aufrufen

Der MCP-Endpoint verwendet JSON-RPC 2.0 über eine einzelne `POST`-Route — kein separater
Handshake ist erforderlich. `tools/call` erwartet den Tool-`name` und dessen `arguments`,
passend zum `inputSchema` des Tools aus `tools/list`:

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/mcp" \
  -H "Authorization: Bearer your-access-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_orders",
      "arguments": {"limit": 10, "search": "smith"}
    }
  }'
```

### Ein erfolgreicher Aufruf

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"orders\": [...], \"totalRegistries\": 3, \"totalPages\": 1}"
      }
    ],
    "structuredContent": {
      "orders": [{ "uid": "order-abc123", "status": "completed" }],
      "totalRegistries": 3,
      "totalPages": 1
    },
    "isError": false
  }
}
```

### Zwei unterschiedliche Arten von Fehlern

MCP unterscheidet zwischen einer Anfrage, die der Server gar nicht erst versuchen konnte
(ein Fehler auf **Protokollebene**, ein JSON-RPC-`error`), und einem Tool, das gelaufen ist
und selbst einen Fehler gemeldet hat (ein Ergebnis auf **Fachebene**). Dieser Endpoint
behält diese Unterscheidung bei, statt beide in dieselbe Form zu pressen:

**Protokollebene — ein `error` auf oberster Ebene, kein `result`.** Ein unbekannter
Tool-`name`, ein fehlender `name`, `arguments`, die kein Objekt sind, ein Argumentschlüssel,
den das `inputSchema` des Tools nicht kennt, oder Argumente, die die eigene
Schema-Validierung des Tools nicht bestehen, scheitern alle *bevor* das Tool läuft, mit
`error.code -32602` (`Invalid params`):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unknown tool: list_orderz",
    "data": { "name": "list_orderz" }
  }
}
```

Eine JSON-RPC-`method` auf oberster Ebene, die dieser Endpoint überhaupt nicht unterstützt
(im Gegensatz zu einem Tool-*Namen* innerhalb von `tools/call`), scheitert ebenso, mit
`error.code -32601` (`Method not found`).

**Fachebene — ein normales `result` mit `isError: true`.** Tool-Name und Argumente waren
gültig, und der Dispatch ist tatsächlich gelaufen — und *das* ist gescheitert: eine
Berechtigung, die dem Token fehlt, oder eine UID, die nicht existiert oder zu einer anderen
Organisation gehört. Das ist kein JSON-RPC-Fehler, sondern ein erfolgreicher RPC-Aufruf,
dessen Payload einen Fehlschlag meldet — genauso geformt wie das Erfolgsbeispiel oben, aber
mit `isError: true`, einer lesbaren Meldung in `content` und einem maschinenlesbaren
`structuredContent.code`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "The authenticated principal lacks the order:read permission required by list_orders." }
    ],
    "structuredContent": { "code": "permission_denied", "required_permission": "order:read" },
    "isError": true
  }
}
```

`structuredContent.code` ist `permission_denied`, wenn dem Token die vom Tool benötigte
Berechtigung fehlt, oder `not_found`, wenn die UID nicht existiert oder zu einer anderen
Organisation gehört.

> [!NOTE]
>
> Auf diesem einen Endpoint werden zwei JSON-RPC-Protokollrevisionen unterstützt: eine
> zustandslose, header-geroutete Form (`Mcp-Protocol-Version: 2026-07-28`), die die meisten
> aktuellen MCP-Clients verwenden, und die frühere `initialize`-Handshake-Form (`2025-11-25`).
> Beide werden transparent behandelt — Ihr MCP-Client wählt die ihm bekannte Revision, eine
> Konfiguration ist nicht erforderlich.

## Header für eigene und headless Clients

Ein interaktiver MCP-Client (Cursor, Claude Desktop) setzt diese automatisch; Sie brauchen
sie nur zu kennen, wenn Sie einen eigenen Client gegen die zustandslose Revision
`2026-07-28` schreiben, statt einen fertigen Client zu verwenden:

| Header | Erforderlich | Beschreibung |
| - | - | - |
| `Mcp-Protocol-Version` | Für `2026-07-28` | Senden Sie `2026-07-28`, um die zustandslose Form ohne Handshake zu nutzen. Lassen Sie ihn weg (oder senden Sie `2025-11-25`), um stattdessen den älteren `initialize`-Handshake zu verwenden. |
| `Mcp-Method` | Für `2026-07-28` | Muss exakt der JSON-RPC-`method` des Bodys entsprechen. Das ermöglicht es Infrastruktur, allein anhand der Header zu routen; der Server lehnt eine Anfrage ab, bei der Header und Body widersprüchlich sind, statt einer Seite blind zu vertrauen. |
| `Mcp-Name` | Für `2026-07-28`, nur bei `tools/call` | Muss exakt `params.name` entsprechen. Dieselbe Widerspruchsprüfung wie bei `Mcp-Method`, bezogen auf das aufgerufene Tool. |

> [!NOTE]
>
> Jeder dieser drei Header darf in der Base64-Sentinel-Form der MCP-Spezifikation gesendet
> werden, `=?base64?<base64-des-werts>?=`, statt als Klartext -- erforderlich, wenn der Wert
> nicht sicher als rohes ASCII-HTTP-Header-Feld übertragen werden kann. Der Server dekodiert
> den Sentinel und vergleicht den *dekodierten* Wert mit dem JSON-RPC-Body; ein nicht
> dekodierbarer Sentinel wird genauso abgelehnt wie ein widersprüchlicher Klartextwert.

Eine `2026-07-28`-Anfrage ohne `Mcp-Method` (oder bei `tools/call` ohne `Mcp-Name`) wird vor
dem Dispatch mit `400` und JSON-RPC-Fehlercode `-32020` abgelehnt — auf dieser Revision sind
diese Header für das Routing tragend, keine optionalen Metadaten. Die Antwort trägt weiterhin
die eigene `id` der Anfrage (eine Header-Routing-Ablehnung ist keine Notification) und ein
`data`-Objekt, das den Header und den Wert nennt, gegen den verglichen wurde:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Mcp-Method is required for protocol version 2026-07-28",
    "data": { "header": "Mcp-Method", "bodyValue": "tools/list" }
  }
}
```

Ein `Mcp-Protocol-Version`-Header, der eine von diesem Endpoint nicht unterstützte Version
nennt, wird mit `400` und JSON-RPC-Fehlercode `-32022` abgelehnt, mit `data.requested` und
`data.supported` (der Liste aus [Zwei JSON-RPC-Protokollrevisionen](#ein-tool-aufrufen)
oben), damit der Client mit einer unterstützten Version erneut versuchen kann:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": { "requested": "1999-01-01", "supported": ["2026-07-28", "2025-11-25"] }
  }
}
```

## Fehlerantworten

| HTTP-Status | Wann | Body |
| - | - | - |
| `200` | Eine JSON-RPC-Anfrage wurde bearbeitet — ein erfolgreicher oder auf Fachebene fehlgeschlagener Tool-Aufruf (`isError: true`), ein Invalid-Params-Fehler (`-32602`, immer `200`, unabhängig von der Protokollrevision), oder der Method-not-found-Fehler eines `2025-11-25`-Clients | `{"result": ...}` oder `{"error": ...}` |
| `202` | Eine JSON-RPC-**Notification** (eine Anfrage ohne `id`) wurde akzeptiert | *(leerer Body)* |
| `400` | Nicht parsbares JSON; ein fehlerhafter JSON-RPC-Umschlag; `Mcp-*`-Routing-Header, die dem Body, sich gegenseitig widersprechen oder fehlen, wo sie erforderlich sind (`-32020`); eine nicht unterstützte `Mcp-Protocol-Version` (`-32022`); oder ein nicht dekodierbarer Base64-Sentinel-Header-Wert | `{"error": {"code": ..., ...}}` |
| `401` | Fehlende oder ungültige Anmeldeinformationen — siehe `WWW-Authenticate`-Header für die Metadaten-URL | `{"code": "...", "description": "..."}` (kein JSON-RPC-Umschlag) |
| `403` | Die Anfrage enthielt einen `Origin`-Header, der nicht auf der Allowlist dieses Dienstes steht (nur Browser-Clients — siehe [oben](#browser-basierte-clients-und-origin-freischaltung)) | `{"error": {"code": -32600, ...}}` |
| `404` | Method not found (`-32601`), **nur** für einen `2026-07-28`-Client; ein `2025-11-25`-Client liest denselben Fehler stattdessen aus einer `200` | `{"error": {"code": -32601, ...}}` |
| `500` | Unerwarteter Serverfehler (bereits gestartete Schreibvorgänge werden zurückgerollt) | `{"error": {"code": -32603, ...}}` |

> [!NOTE]
>
> Ein Fehler auf Tool-Ebene (`permission_denied`, `not_found`) ist **immer** `200` mit
> `result.isError: true` — er wird nie zu einem HTTP-Fehlerstatus. Nur ein Fehler auf
> Protokollebene (fehlerhaftes JSON-RPC, unbekannte Methode oder Tool, ungültige Argumente,
> ein nicht erlaubter `Origin`, ungültige Anmeldeinformationen) ändert den HTTP-Status weg
> von `200`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.