# Einen MCP-Server mit OAuth schützen: Token-Passthrough ablehnen und pro nachgelagerter API tauschen

> Labor mit dem offiziellen MCP-Python-SDK und Keycloak: 401-Handshake, Audience-Prüfung, RFC-8693-Tausch für die Zahlungs-API und ein abgelehntes Passthrough.

- URL: https://iamops.dev/de/mcp-server-no-token-passthrough/
- Language: de
- Author: Argo
- Published: 2026-11-11
- Category: Labs
- Topics: MCP, OAuth, Token Exchange, Keycloak, KI-Agenten

## Kurz gesagt

- Ein MCP-Server ist ein OAuth-Resource-Server: Er antwortet mit 401 und Protected Resource Metadata, damit Clients den Authorization Server finden.
- Er prüft jedes Bearer Token per Introspektion und lehnt eines ab, dessen Audience den MCP-Server selbst nicht enthält.
- Für eine nachgelagerte API tauscht er das Token (RFC 8693), statt das Token des Aufrufers weiterzureichen.
- Ein absichtliches Passthrough scheitert: Das getauschte Token für die Zahlungs-API ist für den MCP-Server inaktiv und liefert 401.
- Protokolliere Nutzer, Agent-Client und nachgelagerte Audience in einer Zeile, damit Audits die Kette nachvollziehen können.

Am 10. November 2026 hat WorkOS Token Exchange (RFC 8693) zu WorkOS Connect hinzugefügt, damit ein MCP-Server nachgelagerte APIs für einen Nutzer aufrufen kann, ohne dessen Token durchzureichen. Genau dieses Muster erwartet die MCP-Autorisierungsspezifikation. Ich habe es von Hand mit dem offiziellen Python-SDK nachgebaut, damit jede Regel sichtbar wird.

Es baut auf dem [Keycloak-Token-Exchange-Labor](https://iamops.dev/de/keycloak-token-exchange-rfc-8693/) auf: gleicher Realm, gleiche drei Clients.

## Was das Labor zeigt

Ein mit dem offiziellen Python-SDK (`mcp` 2.3.0) geschriebener MCP-Server arbeitet als OAuth-*Resource-Server* für einen Keycloak-Realm. Er tut vier Dinge:

1. Er beantwortet eine Anfrage ohne Token mit `401` und einem Verweis auf seine Protected Resource Metadata (RFC 9728), sodass ein Client den Autorisierungsserver finden kann, ohne ihn fest einzutragen.
2. Er prüft jedes Bearer-Token per Introspektion bei Keycloak und lehnt Tokens ab, deren Audience den MCP-Server selbst nicht enthält.
3. Für ein Tool tauscht er das Token des Aufrufers gegen ein Token für die Zahlungs-API (RFC 8693), statt es weiterzureichen.
4. Er lehnt ein für die Zahlungs-API ausgestelltes Token ab, wenn jemand es dem MCP-Server vorlegt (ein Passthrough-Versuch).

Der Verifier ist kurz. Die entscheidende Zeile ist die Audience-Prüfung:

```python
data = introspect(token)            # RFC 7662, as the mcp-server client
aud = data.get("aud", [])
aud = [aud] if isinstance(aud, str) else aud
if not data.get("active") or "mcp-server" not in aud:
    return None                     # inactive, or minted for another API: no passthrough
```

## Der Ablauf

Legen Sie die SDK-Version fest: `mcp` 2.x hat `FastMCP` in `MCPServer` umbenannt, und SDKs ändern ihre Auth-Klassen zwischen Versionen. Der Server lauscht auf `127.0.0.1:8001`.

**Ohne Token.** Die erste Anfrage ist der Discovery-Handshake, mit dem jeder MCP-Client beginnt: ein `401`, dessen `WWW-Authenticate`-Header eine `resource_metadata`-URL enthält, und ein Metadatendokument, das den Realm als Autorisierungsserver nennt.

![Terminalausgabe: Eine Anfrage ohne Token liefert 401 Unauthorized mit einem www-authenticate-Header, der auf die Metadaten der geschützten Ressource verweist; das Metadatendokument nennt den Keycloak-Realm als Autorisierungsserver.](https://iamops.dev/media/mcp-server-no-token-passthrough/03-no-token.webp)

*Der 401-Handshake. Der Client erfährt aus dem Metadatendokument, wo er ein Token bekommt, nicht aus einer Konfiguration.*

**Mit Token.** Ein kleines Skript holt ein Nutzer-Token für den Client `agent`, öffnet eine MCP-Sitzung und ruft beide Tools auf. `whoami` zeigt, dass der Server den Nutzer über den Agent-Client sieht; `downstream_token` zeigt, wie der Server das Token gegen eines tauscht, das auf die Zahlungs-API begrenzt ist.

![Terminalausgabe der beiden Tool-Aufrufe: whoami liefert Subject, Agent-Client und Scopes; downstream_token liefert ein Token mit Audience payments-api und autorisierter Partei mcp-server. Das Subject ist durch einen Platzhalter ersetzt.](https://iamops.dev/media/mcp-server-no-token-passthrough/04-call.webp)

*Zwei Tools. Das erste zeigt, wer aufgerufen hat. Das zweite zeigt das getauschte Token: Audience payments-api, autorisierte Partei mcp-server, gleiches Subject. Das Subject ist ein Platzhalter.*

Derselbe Aufruf funktioniert über den MCP-Inspector-Kommandozeilenclient, den Standardweg, um nachzustellen, was ein MCP-Host tun würde. Legen Sie seine Version in Skripten fest; dieses Labor nutzte 2.15.0.

**Der Passthrough-Versuch.** Erzeugen Sie ein frisches getauschtes Token, betrachten Sie es per Introspektion von beiden Seiten und legen Sie es dem MCP-Server vor.

![Terminalausgabe: Die Introspektion meldet das Token als aktiv für den Client payments-api und als inaktiv für den Client mcp-server; die Vorlage beim MCP-Server liefert 401.](https://iamops.dev/media/mcp-server-no-token-passthrough/06-passthrough.webp)

*Kein Passthrough. Keycloak meldet das Token nur dem Client als aktiv, für den es ausgestellt wurde. Der MCP-Server antwortet mit 401. Client Secrets sind Platzhalter.*

## Stolperfallen

- **Introspektion oder lokale Validierung?** Das Labor nutzt Introspektion: sofortiger Widerruf, dafür ein Roundtrip zum Autorisierungsserver. Die Alternative ist lokale JWT-Validierung gegen die JWKS; notieren Sie, was Sie verlieren und gewinnen.
- **Prüfen Sie die Audience, nicht nur die Signatur.** Ein gültiges Token für eine andere API bleibt das falsche Token. Die Audience-Prüfung macht aus dem Passthrough ein `401`.
- **Tokens leben in diesem Aufbau fünf Minuten**; erzeugen Sie das Passthrough-Token also direkt vor dem Test.
- **SDK-Drift.** Klassennamen und Auth-Hooks haben sich zwischen Hauptversionen verschoben; testen Sie mit der Version, die Sie ausliefern.

## Sicherheitserkenntnisse

1. Ein MCP-Server ist ein OAuth-Resource-Server. Er veröffentlicht Metadaten, validiert die Audience und lehnt alles ab, was nicht für ihn bestimmt ist.
2. Reichen Sie das Token des Aufrufers nie an eine nachgelagerte API weiter. Tauschen Sie es pro nachgelagerter Audience, enger gefasst und kurzlebig.
3. Lassen Sie den Autorisierungsserver entscheiden, wer ein Token als aktiv sieht. Ein Token, das nur beim vorgesehenen Empfänger funktioniert, begrenzt, was ein kompromittierter Zwischenschritt anrichten kann.
4. Protokollieren Sie eine Zeile, die Nutzer, Agent-Client und nachgelagerte Audience verbindet; das Token allein erzählt einem Auditor nicht die ganze Geschichte.

## Was nicht ausgeführt wurde

Der OAuth-Ablauf der MCP-Inspector-Weboberfläche wurde nicht ausgeführt (der Client `agent` des Labors erlaubt dafür eine localhost-Weiterleitung). Dynamische Client-Registrierung wurde nicht verwendet; der Client ist vorregistriert. Alles lief auf einem Rechner mit Wegwerfkonten. Für dieses Labor wird keine Aufzeichnung veröffentlicht.

*Die Terminalbilder wurden aus der gespeicherten Ausgabe des Laufs erzeugt; Kennungen, Geheimnisse und Zeitstempel sind durch Platzhalter ersetzt.*

## Dieses Lab nachbauen

Dieses Lab läuft in etwa 30 Minuten auf einem Laptop. Sie brauchen den Keycloak-Realm aus dem Token-Exchange-Lab, einen kleinen MCP-Server in Python und ein paar curl-Aufrufe. Öffnen Sie jeden Schritt, kopieren Sie die Blöcke und vergleichen Sie die Ausgabe mit meiner.

Jeder Wert in spitzen Klammern ist ein Platzhalter für Ihre Testumgebung. Nichts auf dieser Seite ist eine echte Kennung oder ein echtes Geheimnis.

**Variablen einmal setzen** `env.sh` (bash)

```bash
# Paste into every terminal you use for this lab. Same values as in the Keycloak lab.
export KC_URL="http://localhost:8080"
export KC_REALM="agentlab"
export ALICE_PASSWORD='<ALICE_PASSWORD>'
export AGENT_SECRET='<AGENT_CLIENT_SECRET>'
export MCP_SECRET='<MCP_SERVER_CLIENT_SECRET>'
export PAYMENTS_SECRET='<PAYMENTS_API_CLIENT_SECRET>'
export TOKEN_URL="$KC_URL/realms/$KC_REALM/protocol/openid-connect/token"
export INTROSPECT_URL="$TOKEN_URL/introspect"
export MCP_URL="http://127.0.0.1:8001/mcp"
```

### Schritt 1: SDK installieren und Realm prüfen

**Ziel.** Installieren Sie das MCP-Python-SDK in einer sauberen virtualenv und prüfen Sie, ob der Keycloak-Realm aus dem ersten Lab noch läuft.

**Voraussetzungen**

- Das Keycloak-Lab läuft mit Realm, drei Clients und dem Benutzer alice
- Python 3.12 oder neuer, curl und jq

`install.sh` (bash)

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install "mcp==2.3.0" httpx
# the realm answers
curl -s -o /dev/null -w "%{http_code}\n" "$KC_URL/realms/$KC_REALM/.well-known/openid-configuration"
```

**Erwartete Ausgabe**

```text
Successfully installed ... httpx-... mcp-2.3.0 ...
200
```

### Schritt 2: MCP-Server schreiben und starten

**Ziel.** Starten Sie einen MCP-Server, der jedes Token per Introspektion prüft und alle ablehnt, die nicht für ihn bestimmt sind.

**Voraussetzungen**

- Die virtualenv aus dem vorigen Schritt ist aktiv
- Die Variablen aus env.sh sind in diesem Terminal gesetzt, und Port 8001 ist frei

`payments_mcp.py` (python)

```python
"""An MCP server that is an OAuth resource server for Keycloak, and calls a downstream API
for the user with RFC 8693 token exchange. Tested with mcp 2.3.0 and Keycloak 26.8.2. Lab use only."""
import base64
import json
import os

import httpx
from mcp.server.auth.middleware.auth_context import get_access_token
from mcp.server.auth.provider import AccessToken
from mcp.server.auth.settings import AuthSettings
from mcp.server.mcpserver import MCPServer

KC = f"{os.environ['KC_URL']}/realms/{os.environ['KC_REALM']}"
CLIENT_ID = "mcp-server"
CLIENT_SECRET = os.environ["MCP_SECRET"]
RESOURCE = "http://localhost:8001/mcp"


class IntrospectionVerifier:
    """RFC 7662 introspection at Keycloak, then an audience check."""

    async def verify_token(self, token: str) -> AccessToken | None:
        async with httpx.AsyncClient() as http:
            r = await http.post(f"{KC}/protocol/openid-connect/token/introspect",
                                data={"token": token}, auth=(CLIENT_ID, CLIENT_SECRET))
        data = r.json()
        aud = data.get("aud", [])
        aud = [aud] if isinstance(aud, str) else aud
        if not data.get("active") or CLIENT_ID not in aud:
            return None  # inactive, or minted for another API: no token passthrough
        return AccessToken(token=token, client_id=data.get("azp", ""),
                           scopes=data.get("scope", "").split(), expires_at=data.get("exp"),
                           subject=data.get("sub"), claims={"iss": data.get("iss")})


mcp = MCPServer(
    "payments-lab",
    token_verifier=IntrospectionVerifier(),
    auth=AuthSettings(issuer_url=KC, resource_server_url=RESOURCE, validate_token_resource=False),
)


def claims(jwt: str) -> dict:
    part = jwt.split(".")[1]
    return json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))


@mcp.tool()
async def whoami() -> dict:
    """Who called this MCP server, according to the bearer token."""
    t = get_access_token()
    return {"subject": t.subject, "client": t.client_id, "scopes": t.scopes}


@mcp.tool()
async def downstream_token() -> dict:
    """Exchange the caller's token for a payments-api token (RFC 8693) and show its claims."""
    t = get_access_token()
    async with httpx.AsyncClient() as http:
        r = await http.post(f"{KC}/protocol/openid-connect/token", auth=(CLIENT_ID, CLIENT_SECRET), data={
            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
            "subject_token": t.token,
            "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
            "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
            "audience": "payments-api",
            "scope": "aud-payments-api",
        })
    body = r.json()
    if "access_token" not in body:
        return {"error": body}
    c = claims(body["access_token"])
    return {k: c.get(k) for k in ("aud", "azp", "sub", "scope", "exp")}


if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8001)
```

`run-server.sh` (bash)

```bash
python payments_mcp.py   # keep this terminal open
```

**Erwartete Ausgabe**

```text
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
```

### Schritt 3: Den Server ohne Token aufrufen

**Ziel.** Sehen Sie sich den Discovery-Handshake an: ein 401, das auf die Protected Resource Metadata zeigt, und ein Metadatendokument, das den Realm nennt.

**Voraussetzungen**

- Der Server aus dem vorigen Schritt läuft
- Nutzen Sie ein zweites Terminal mit geladenem env.sh

`no-token.sh` (bash)

```bash
curl -si -X POST "$MCP_URL" -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' -d '{}' | grep -iE '^HTTP|www-authenticate'
curl -s http://127.0.0.1:8001/.well-known/oauth-protected-resource/mcp | jq .
```

**Erwartete Ausgabe**

```text
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://localhost:8001/.well-known/oauth-protected-resource/mcp"
{
  "resource": "http://localhost:8001/mcp",
  "authorization_servers": [
    "http://localhost:8080/realms/agentlab"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}
```

### Schritt 4: Beide Tools mit einem Benutzer-Token aufrufen

**Ziel.** Holen Sie ein Token für den Client agent, öffnen Sie eine MCP-Sitzung und rufen Sie whoami und downstream_token auf.

**Voraussetzungen**

- Der Server läuft noch im ersten Terminal
- jq ist installiert; das Skript nutzt den Password Grant, nur für Labs

`call.sh` (bash)

```bash
#!/usr/bin/env bash
# Get a user token for the agent client, open an MCP session and call both tools with curl.
set -euo pipefail
TOKEN=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
  -d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
H=(-H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream')
SID=$(curl -s -D - -o /dev/null "${H[@]}" "$MCP_URL" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r')
curl -s "${H[@]}" -H "mcp-session-id: $SID" -H 'mcp-protocol-version: 2025-06-18' "$MCP_URL" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
for TOOL in whoami downstream_token; do
  echo "--- $TOOL"
  curl -s "${H[@]}" -H "mcp-session-id: $SID" -H 'mcp-protocol-version: 2025-06-18' "$MCP_URL" \
    -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":{}}}" | sed -n 's/^data: //p' | jq -r '.result.content[0].text'
done
```

`run-call.sh` (bash)

```bash
chmod +x call.sh && ./call.sh
```

**Erwartete Ausgabe**

```text
--- whoami
{
  "subject": "<user-id>",
  "client": "agent",
  "scopes": [
    "openid",
    "profile",
    "aud-mcp-server",
    "email"
  ]
}
--- downstream_token
{
  "aud": "payments-api",
  "azp": "mcp-server",
  "sub": "<user-id>",
  "scope": "aud-payments-api profile email",
  "exp": <timestamp>
}
```

### Schritt 5: Absichtlich ein Passthrough versuchen

**Ziel.** Nehmen Sie das Token, das für die Zahlungs-API ausgestellt wurde, und zeigen Sie es dem MCP-Server. Es muss abgelehnt werden.

**Voraussetzungen**

- Ein frisch getauschtes Token: es lebt 5 Minuten, also führe das gleich aus

`passthrough.sh` (bash)

```bash
# 1. a user token for the agent, then the exchange as the MCP server (same calls as in the Keycloak lab)
USER_AT=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
  -d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
T=$(curl -s -u "mcp-server:$MCP_SECRET" -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token="$USER_AT" -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL" | jq -r .access_token)
# 2. who may see that token as active?
curl -s -u "payments-api:$PAYMENTS_SECRET" -d token="$T" "$INTROSPECT_URL" | jq -c '{caller:"payments-api",active,aud,azp}'
curl -s -u "mcp-server:$MCP_SECRET" -d token="$T" "$INTROSPECT_URL" | jq -c '{caller:"mcp-server",active,aud,azp}'
# 3. present it to the MCP server
curl -s -o /dev/null -w "%{http_code}\n" "$MCP_URL" -H "authorization: Bearer $T" \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{}'
```

**Erwartete Ausgabe**

```text
{"caller":"payments-api","active":true,"aud":["payments-api","account"],"azp":"mcp-server"}
{"caller":"mcp-server","active":false,"aud":null,"azp":null}
401
```

### Schritt 6: Aufräumen

**Ziel.** Stoppen Sie den Server, löschen Sie die virtualenv und das Skript und entfernen Sie die Secrets aus der Shell.

**Voraussetzungen**

- Keycloak räumen Sie im Keycloak-Lab auf, im Schritt Aufräumen

`cleanup.sh` (bash)

```bash
pkill -f payments_mcp.py || true
deactivate 2>/dev/null || true
rm -rf .venv payments_mcp.py call.sh
unset ALICE_PASSWORD AGENT_SECRET MCP_SECRET PAYMENTS_SECRET USER_AT T
# check: nothing listens on port 8001 any more
curl -s -o /dev/null -w "%{http_code}\n" "$MCP_URL"
```

**Erwartete Ausgabe**

```text
000
```


## Sources

- [Model Context Protocol specification: Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728)
- [RFC 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662)
- [RFC 8693: OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693)
- [WorkOS changelog, 10 Nov 2026: Token exchange for WorkOS Connect](https://workos.com/changelog/token-exchange-for-workos-connect)
