En resumen
- Un servidor MCP es un servidor de recursos OAuth: responde 401 con los Protected Resource Metadata para que los clientes encuentren el servidor de autorización.
- Hace introspección de cada token de portador y rechaza el que no incluye al propio servidor MCP en su audiencia.
- Para una API posterior intercambia el token (RFC 8693) en lugar de reenviar el del llamante.
- Un passthrough deliberado falla: el token para la API de pagos está inactivo para el servidor MCP, que responde 401.
- Registra usuario, cliente del agente y audiencia posterior en una sola línea para que las auditorías sigan la cadena.
Repite este lab
Escribí este lab para que puedas repetirlo tú mismo. Cada paso tiene los comandos para copiar y la salida que obtuve yo, y puedes marcarlo como hecho. Las marcas se quedan solo en este navegador.
Copia un prompt listo para Claude Code, Cursor, Codex o cualquier agente de código. Solo para entornos de prueba.
Mostrar el prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Proteger un servidor MCP con OAuth: rechazar el token passthrough e intercambiar por cada API posterior Read the whole lab here (Markdown): https://iamops.dev/es/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.
El 10 de noviembre de 2026 WorkOS añadió el intercambio de tokens (RFC 8693) a WorkOS Connect para que un servidor MCP pueda llamar a API posteriores por un usuario sin reenviar el token de este. Es el patrón que espera la especificación de autorización de MCP. Lo construí a mano con el SDK oficial de Python, para ver cada regla en acción.
Se apoya en el laboratorio de intercambio de tokens con Keycloak: mismo realm, mismos tres clientes.
Qué muestra el laboratorio#
Un servidor MCP escrito con el SDK oficial de Python (mcp 2.3.0) actúa como servidor de recursos OAuth de un realm de Keycloak. Hace cuatro cosas:
- Responde a una petición sin token con
401y una referencia a sus Protected Resource Metadata (RFC 9728), de modo que un cliente encuentra el servidor de autorización sin tenerlo fijado en la configuración. - Comprueba cada token de portador por introspección en Keycloak y rechaza los tokens cuya audiencia no incluya al propio servidor MCP.
- Para una herramienta, intercambia el token del llamante por un token destinado a la API de pagos (RFC 8693) en lugar de reenviarlo.
- Rechaza un token emitido para la API de pagos cuando alguien se lo presenta al servidor MCP (un intento de passthrough).
El verificador es corto. La línea decisiva es la comprobación de la audiencia:
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 passthroughLa ejecución#
Fije la versión del SDK: mcp 2.x renombró FastMCP a MCPServer, y los SDK cambian sus clases de autenticación entre versiones. El servidor escucha en 127.0.0.1:8001.
Sin token. La primera petición es el handshake de descubrimiento con el que empieza todo cliente MCP: un 401 cuya cabecera WWW-Authenticate lleva una URL resource_metadata, y un documento de metadatos que nombra al realm como servidor de autorización.

Con token. Un pequeño script obtiene un token de usuario para el cliente agent, abre una sesión MCP y llama a las dos herramientas. whoami muestra que el servidor ve al usuario a través del cliente agente; downstream_token muestra al servidor cambiando el token por otro limitado a la API de pagos.

La misma llamada funciona con el cliente de línea de comandos MCP Inspector, la forma estándar de reproducir lo que haría cualquier host MCP. Fije su versión en los scripts; este laboratorio usó la 2.15.0.
El intento de passthrough. Cree un token intercambiado nuevo, obsérvelo por introspección desde ambos lados y preséntelo al servidor MCP.

Trampas habituales#
- ¿Introspección o validación local? El laboratorio usa introspección: revocación inmediata a cambio de una ida y vuelta al servidor de autorización. La alternativa es validar el JWT localmente con las claves JWKS; anote qué se pierde y qué se gana.
- Compruebe la audiencia, no solo la firma. Un token válido para otra API sigue siendo el token equivocado. La comprobación de audiencia convierte el passthrough en un
401. - Los tokens duran cinco minutos en esta configuración, así que genere el token del passthrough justo antes de la prueba.
- Deriva de los SDK. Los nombres de clases y los ganchos de autenticación cambiaron entre versiones mayores; pruebe con la versión que vaya a desplegar.
Conclusiones de seguridad#
- Un servidor MCP es un servidor de recursos OAuth. Publica metadatos, valida la audiencia y rechaza todo lo que no vaya dirigido a él.
- No reenvíe nunca el token del llamante a una API posterior. Intercámbielo por cada audiencia posterior, más estrecho y de corta duración.
- Deje que el servidor de autorización decida quién ve un token como activo. Un token que solo funciona para su destinatario limita lo que puede hacer un eslabón comprometido.
- Registre una línea que una al usuario, cliente agente y audiencia posterior; el token por sí solo no cuenta la historia completa a un auditor.
Qué no se ejecutó#
No se ejecutó el flujo OAuth de la interfaz web de MCP Inspector (el cliente agent del laboratorio admite para ello una redirección a localhost). No se usó el registro dinámico de clientes; el cliente está preregistrado. Todo se ejecutó en una sola máquina con cuentas desechables. Para este laboratorio no se publica ninguna grabación.
Las imágenes del terminal se generaron a partir de la salida guardada de la ejecución, con identificadores, secretos y marcas de tiempo sustituidos por marcadores.
Repite este lab#
Este lab se ejecuta en un portátil en unos 30 minutos. Hace falta el realm de Keycloak del lab de intercambio de tokens, un pequeño servidor MCP en Python y unas llamadas curl. Abre cada paso, copia los bloques y compara la salida con la mía.
Cada valor entre corchetes angulares es un marcador para tu entorno de prueba. Nada en esta página es un identificador o secreto real.
Define tus variables una sola vez
# 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" 0 de 6 pasos hechos
Paso 1Instala el SDK y comprueba el realm
Objetivo. Instala el SDK de Python de MCP en un virtualenv limpio y comprueba que el realm de Keycloak del primer lab sigue en marcha.
Requisitos
- El lab de Keycloak está en marcha con su realm, tres clientes y el usuario alice
- Python 3.12 o posterior, curl y 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" Salida esperada
Successfully installed ... httpx-... mcp-2.3.0 ...
200 Paso 2Escribe e inicia el servidor MCP
Objetivo. Ejecuta un servidor MCP que comprueba cada token por introspección y rechaza los que no van dirigidos a él.
Requisitos
- El virtualenv del paso anterior está activo
- Las variables de env.sh están definidas en esta terminal y el puerto 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 Salida esperada
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) Paso 3Llama al servidor sin token
Objetivo. Mira el handshake de descubrimiento: un 401 que apunta a los Protected Resource Metadata y un documento de metadatos que nombra el realm.
Requisitos
- El servidor del paso anterior está en marcha
- Usa una segunda terminal con env.sh cargado
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 . Salida esperada
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"
]
} Paso 4Llama a las dos herramientas con un token de usuario
Objetivo. Obtén un token para el cliente agent, abre una sesión MCP y llama a whoami y downstream_token.
Requisitos
- El servidor sigue en marcha en la primera terminal
- jq instalado; el script usa el password grant, solo para 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 Salida esperada
--- 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>
} Paso 5Prueba un passthrough a propósito
Objetivo. Toma el token emitido para la API de pagos y preséntalo al servidor MCP. Debe ser rechazado.
Requisitos
- Un token intercambiado recién emitido: dura 5 minutos, así que ejecútalo enseguida
# 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 '{}' Salida esperada
{"caller":"payments-api","active":true,"aud":["payments-api","account"],"azp":"mcp-server"}
{"caller":"mcp-server","active":false,"aud":null,"azp":null}
401 Paso 6Limpieza
Objetivo. Detén el servidor, borra el virtualenv y el script y elimina los secretos de la shell.
Requisitos
- Keycloak se limpia en el lab de Keycloak, en el paso de limpieza
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" Salida esperada
000 Fuentes#
Comenta este artículo#
¿Te ha servido? Compártelo y dime qué piensas.
Este artículo en Markdown · RSS · JSON feed
Nuevos artículos por correo
Un correo a la semana con nuevos artículos y labs. Puedes darte de baja cuando quieras.
Tu dirección se guarda en Kit, el servicio que envía los correos. Detalles