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.
Refaire ce lab
J’ai écrit ce lab pour que vous puissiez le refaire vous-même. Chaque étape contient les commandes à copier et la sortie que j’ai obtenue, et vous pouvez la cocher une fois faite. Les coches restent uniquement dans ce navigateur.
Copie un prompt prêt à l’emploi pour Claude Code, Cursor, Codex ou tout autre agent de code. Pour les environnements de test uniquement.
Afficher le prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Protéger un serveur MCP avec OAuth : refuser le token passthrough et échanger pour chaque API en aval Read the whole lab here (Markdown): https://iamops.dev/fr/mcp-server-no-token-passthrough.md What the lab needs before the first step: - The Keycloak lab is running with its realm, three clients and user alice - Python 3.12 or newer, curl and jq - Values I have to set myself (the lab uses placeholders): <ALICE_PASSWORD>, <AGENT_CLIENT_SECRET>, <MCP_SERVER_CLIENT_SECRET>, <PAYMENTS_API_CLIENT_SECRET> How I want you to work: 1. Read the lab from start to finish first (each step lists its own prerequisites). Then check that the prerequisites are in place and that the tool versions match what the lab expects. Tell me what is missing before you run anything. 2. Run one step at a time. Before each command, show it to me and say in a sentence what it does. 3. Ask me before anything that costs money, creates cloud resources, touches a real tenant or account, or deletes anything. Wait for my answer. 4. Use the placeholders from the lab. Never paste real secrets, tokens or production identities into a command, a file or this chat. If a value is needed, tell me where to set it myself. 5. After each step, compare the output with the expected output in the lab. If it does not match, stop and tell me what differs. Do not carry on or invent a fix without asking me. 6. At the end, report what passed, what failed and which cleanup you did. Then offer to tick the steps off for me. The lab page keeps ticks only in my browser, so if you cannot do that, list the steps I should tick. This lab is for test environments only. Do not run it against production, or against a tenant or account that holds real data or real users. You may answer in my language.
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 : 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 :
- Il répond à une requête sans jeton par
401et un renvoi vers ses Protected Resource Metadata (RFC 9728), si bien qu’un client trouve le serveur d’autorisation sans l’avoir en configuration. - 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.
- 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.
- 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 :
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 passthroughLe 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.

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.

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.

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é#
- 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é.
- 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.
- 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.
- 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
# 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" Étapes terminées : 0 sur 6
Étape 1Installer 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
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
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
"""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) python payments_mcp.py # keep this terminal open Résultat attendu
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 3Appeler 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é
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
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 4Appeler 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
#!/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 chmod +x call.sh && ./call.sh Résultat attendu
--- 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 5Tenter 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
# 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
{"caller":"payments-api","active":true,"aud":["payments-api","account"],"azp":"mcp-server"}
{"caller":"mcp-server","active":false,"aud":null,"azp":null}
401 Étape 6Nettoyage
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
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
000 Sources#
Discuter de cet article#
Utile ? Partagez-le et dites-moi ce que vous en pensez.
Cet article en Markdown · RSS · JSON feed
Les nouveaux articles par e-mail
Un e-mail par semaine avec les nouveaux articles et labs. Désinscription à tout moment.
Votre adresse est conservée chez Kit, le service qui envoie les e-mails. Détails