# Protéger un serveur MCP avec OAuth : refuser le token passthrough et échanger pour chaque API en aval

> Lab avec le SDK Python de MCP et Keycloak : handshake 401, contrôle d'audience, échange RFC 8693 pour l'API de paiement et passthrough refusé par le serveur.

- URL: https://iamops.dev/fr/mcp-server-no-token-passthrough/
- Language: fr
- Author: Argo
- Published: 2026-11-11
- Category: Labs
- Topics: MCP, OAuth, Token Exchange, Keycloak, Agents d'IA

## En bref

- Un serveur MCP est un serveur de ressources OAuth : il répond 401 avec les Protected Resource Metadata pour que les clients trouvent le serveur d'autorisation.
- Il fait l'introspection de chaque jeton porteur et refuse celui dont l'audience n'inclut pas le serveur MCP lui-même.
- Pour une API en aval, il échange le jeton (RFC 8693) au lieu de transmettre celui de l'appelant.
- Un passthrough délibéré échoue : le jeton pour l'API de paiement est inactif pour le serveur MCP, qui répond 401.
- Journalisez l'utilisateur, le client de l'agent et l'audience en aval sur une seule ligne pour que les audits suivent la chaîne.

Le 10 novembre 2026, WorkOS a ajouté l'échange de jetons (RFC 8693) à WorkOS Connect pour qu'un serveur MCP puisse appeler des API en aval pour un utilisateur sans transmettre le jeton de celui-ci. C'est le schéma qu'attend la spécification d'autorisation MCP. Je l'ai construit à la main avec le SDK Python officiel, pour voir chaque règle à l'œuvre.

Il prolonge le [laboratoire d'échange de jetons avec Keycloak](https://iamops.dev/fr/keycloak-token-exchange-rfc-8693/) : même realm, mêmes trois clients.

## Ce que montre le laboratoire

Un serveur MCP écrit avec le SDK Python officiel (`mcp` 2.3.0) joue le rôle de *serveur de ressources* OAuth pour un realm Keycloak. Il fait quatre choses :

1. Il répond à une requête sans jeton par `401` et un renvoi vers ses Protected Resource Metadata (RFC 9728), si bien qu'un client trouve le serveur d'autorisation sans l'avoir en configuration.
2. Il vérifie chaque jeton porteur par introspection auprès de Keycloak et refuse les jetons dont l'audience n'inclut pas le serveur MCP lui-même.
3. Pour un outil, il échange le jeton de l'appelant contre un jeton destiné à l'API de paiement (RFC 8693) au lieu de le transmettre.
4. Il refuse un jeton émis pour l'API de paiement quand quelqu'un le présente au serveur MCP (une tentative de passthrough).

Le vérificateur est court. La ligne décisive est le contrôle de l'audience :

```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
```

## Le déroulement

Figez la version du SDK : `mcp` 2.x a renommé `FastMCP` en `MCPServer`, et les SDK changent leurs classes d'authentification d'une version à l'autre. Le serveur écoute sur `127.0.0.1:8001`.

**Sans jeton.** La première requête est le handshake de découverte par lequel commence tout client MCP : un `401` dont l'en-tête `WWW-Authenticate` porte une URL `resource_metadata`, et un document de métadonnées qui désigne le realm comme serveur d'autorisation.

![Sortie du terminal : une requête sans jeton renvoie 401 Unauthorized avec un en-tête www-authenticate qui pointe vers les métadonnées de la ressource protégée ; le document de métadonnées désigne le realm Keycloak comme serveur d'autorisation.](https://iamops.dev/media/mcp-server-no-token-passthrough/03-no-token.webp)

*Le handshake 401. Le client apprend où obtenir un jeton grâce au document de métadonnées, pas grâce à la configuration.*

**Avec un jeton.** Un petit script obtient un jeton utilisateur pour le client `agent`, ouvre une session MCP et appelle les deux outils. `whoami` montre que le serveur voit l'utilisateur à travers le client agent ; `downstream_token` montre le serveur qui échange le jeton contre un jeton limité à l'API de paiement.

![Sortie du terminal des deux appels d'outils : whoami renvoie le sujet, le client agent et ses scopes ; downstream_token renvoie un jeton d'audience payments-api et de partie autorisée mcp-server. Le sujet est remplacé par un espace réservé.](https://iamops.dev/media/mcp-server-no-token-passthrough/04-call.webp)

*Deux outils. Le premier montre qui a appelé. Le second montre le jeton échangé : audience payments-api, partie autorisée mcp-server, même sujet. Le sujet est un espace réservé.*

Le même appel fonctionne avec le client en ligne de commande MCP Inspector, la façon standard de reproduire ce que ferait n'importe quel hôte MCP. Figez sa version dans les scripts ; ce laboratoire a utilisé la 2.15.0.

**La tentative de passthrough.** Créez un jeton échangé tout neuf, regardez-le en introspection des deux côtés, puis présentez-le au serveur MCP.

![Sortie du terminal : l'introspection indique le jeton comme actif pour le client payments-api et inactif pour le client mcp-server ; le présenter au serveur MCP renvoie 401.](https://iamops.dev/media/mcp-server-no-token-passthrough/06-passthrough.webp)

*Pas de passthrough. Keycloak ne signale le jeton comme actif qu'au client pour lequel il a été émis. Le serveur MCP répond 401. Les secrets de client sont des espaces réservés.*

## Pièges

- **Introspection ou validation locale ?** Le laboratoire utilise l'introspection : révocation immédiate, au prix d'un aller-retour vers le serveur d'autorisation. L'alternative est la validation locale du JWT avec les clés JWKS ; notez ce que l'on perd et ce que l'on gagne.
- **Contrôlez l'audience, pas seulement la signature.** Un jeton valable pour une autre API reste le mauvais jeton. C'est le contrôle d'audience qui transforme le passthrough en `401`.
- **Les jetons vivent cinq minutes** dans cette configuration : générez le jeton de passthrough juste avant le test.
- **Dérive des SDK.** Les noms de classes et les points d'accroche d'authentification ont bougé entre versions majeures ; testez avec la version que vous livrez.

## Enseignements de sécurité

1. Un serveur MCP est un serveur de ressources OAuth. Il publie des métadonnées, valide l'audience et refuse tout ce qui ne lui est pas destiné.
2. Ne transmettez jamais le jeton de l'appelant à une API en aval. Échangez-le pour chaque audience en aval, plus étroit et de courte durée.
3. Laissez le serveur d'autorisation décider qui voit un jeton comme actif. Un jeton qui ne fonctionne que pour son destinataire limite ce qu'un maillon compromis peut faire.
4. Journalisez une ligne qui relie utilisateur, client agent et audience en aval ; le jeton seul ne raconte pas toute l'histoire à un auditeur.

## Ce qui n'a pas été exécuté

Le flux OAuth de l'interface web de MCP Inspector n'a pas été exécuté (le client `agent` du laboratoire autorise pour cela une redirection vers localhost). L'enregistrement dynamique de clients n'a pas été utilisé ; le client est préenregistré. Tout a tourné sur une seule machine avec des comptes jetables. Aucun enregistrement n'est publié pour ce laboratoire.

*Les images du terminal ont été générées à partir de la sortie enregistrée de l'exécution, avec identifiants, secrets et horodatages remplacés par des espaces réservés.*

## Refaire ce lab

Ce lab tourne sur un portable en une demi-heure environ. Il faut le realm Keycloak du lab sur l'échange de jetons, un petit serveur MCP en Python et quelques appels curl. Ouvrez chaque étape, copiez les blocs et comparez la sortie avec la mienne.

Chaque valeur entre chevrons est un espace réservé pour votre environnement de test. Rien sur cette page n’est un identifiant ou un secret réel.

**Définissez vos variables une seule fois** `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"
```

### Étape 1: Installer le SDK et vérifier le realm

**Objectif.** Installez le SDK Python de MCP dans un virtualenv propre et vérifiez que le realm Keycloak du premier lab tourne toujours.

**Prérequis**

- Le lab Keycloak tourne avec son realm, ses trois clients et l'utilisateur alice
- Python 3.12 ou plus récent, curl et 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"
```

**Résultat attendu**

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

### Étape 2: Écrire et démarrer le serveur MCP

**Objectif.** Lancez un serveur MCP qui vérifie chaque jeton par introspection et refuse ceux qui ne lui sont pas destinés.

**Prérequis**

- Le virtualenv de l'étape précédente est actif
- Les variables de env.sh sont définies dans ce terminal et le port 8001 est libre

`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
```

**Résultat attendu**

```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)
```

### Étape 3: Appeler le serveur sans jeton

**Objectif.** Observez la découverte : un 401 qui renvoie vers les Protected Resource Metadata et un document de métadonnées qui nomme le realm.

**Prérequis**

- Le serveur de l'étape précédente tourne
- Utilisez un second terminal avec env.sh chargé

`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 .
```

**Résultat attendu**

```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"
  ]
}
```

### Étape 4: Appeler les deux outils avec un jeton utilisateur

**Objectif.** Obtenez un jeton pour le client agent, ouvrez une session MCP et appelez whoami et downstream_token.

**Prérequis**

- Le serveur tourne toujours dans le premier terminal
- jq installé ; le script utilise le password grant, réservé aux 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
```

**Résultat attendu**

```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>
}
```

### Étape 5: Tenter un passthrough exprès

**Objectif.** Prenez le jeton émis pour l'API de paiement et présentez-le au serveur MCP. Il doit être refusé.

**Prérequis**

- Un jeton échangé tout frais : il dure 5 minutes, exécutez donc ceci tout de suite

`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 '{}'
```

**Résultat attendu**

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

### Étape 6: Nettoyage

**Objectif.** Arrêtez le serveur, supprimez le virtualenv et le script, et effacez les secrets du shell.

**Prérequis**

- Keycloak se nettoie dans le lab Keycloak, à l'étape Nettoyage

`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"
```

**Résultat attendu**

```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)
