iamops.dev
Argo en X Feed RSS
ESEspañol

Labs Técnico 4 min de lectura

Proteger un servidor MCP con OAuth: rechazar el token passthrough e intercambiar por cada API posterior

Laboratorio con el SDK Python de MCP y Keycloak: handshake 401, audiencia, intercambio RFC 8693 para la API de pagos y passthrough rechazado en un servidor.

Dos capturas del terminal de mi laboratorio: una petición MCP sin token rechazada con 401 y una introspección que muestra un token activo para la API de pagos pero inactivo para el servidor MCP.
En resumenUn servidor MCP es un servidor de recursos OAuth: responde 401 con los…
  • 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 6 pasos

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.

Ir a los pasos

Cómo funciona

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:

  1. Responde a una petición sin token con 401 y 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.
  2. Comprueba cada token de portador por introspección en Keycloak y rechaza los tokens cuya audiencia no incluya al propio servidor MCP.
  3. Para una herramienta, intercambia el token del llamante por un token destinado a la API de pagos (RFC 8693) en lugar de reenviarlo.
  4. 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:

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

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

Salida de terminal: una petición sin token devuelve 401 Unauthorized con una cabecera www-authenticate que apunta a los metadatos del recurso protegido; el documento de metadatos nombra al realm de Keycloak como servidor de autorización.
El handshake 401. El cliente sabe dónde conseguir un token por el documento de metadatos, no por la configuració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.

Salida de terminal de las dos llamadas a herramientas: whoami devuelve el sujeto, el cliente agente y sus scopes; downstream_token devuelve un token con audiencia payments-api y parte autorizada mcp-server. El sujeto está sustituido por un marcador.
Dos herramientas. La primera muestra quién llamó. La segunda muestra el token intercambiado: audiencia payments-api, parte autorizada mcp-server, mismo sujeto. El sujeto es un marcador.

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.

Salida de terminal: la introspección indica el token como activo para el cliente payments-api e inactivo para el cliente mcp-server; presentarlo al servidor MCP devuelve 401.
Sin passthrough. Keycloak solo informa del token como activo al cliente para el que se emitió. El servidor MCP responde 401. Los secretos de cliente son marcadores.

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#

  1. Un servidor MCP es un servidor de recursos OAuth. Publica metadatos, valida la audiencia y rechaza todo lo que no vaya dirigido a él.
  2. 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.
  3. 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.
  4. 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

bash · env.sh
# 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"
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
bash · install.sh
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

salida
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
python · payments_mcp.py
"""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)
bash · run-server.sh
python payments_mcp.py   # keep this terminal open

Salida esperada

salida
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
bash · no-token.sh
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

salida
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
bash · call.sh
#!/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
bash · run-call.sh
chmod +x call.sh && ./call.sh

Salida esperada

salida
--- 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
bash · passthrough.sh
# 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

salida
{"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
bash · cleanup.sh
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

salida
000

Fuentes#

Comenta este artículo#

¿Te ha servido? Compártelo y dime qué piensas.

Seguir en X

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

Artículos y labs relacionados