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

- URL: https://iamops.dev/es/mcp-server-no-token-passthrough/
- Language: es
- Author: Argo
- Published: 2026-11-11
- Category: Labs
- Topics: MCP, OAuth, Intercambio de tokens, Keycloak, Agentes de IA

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

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](https://iamops.dev/es/keycloak-token-exchange-rfc-8693/): 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.](https://iamops.dev/media/mcp-server-no-token-passthrough/03-no-token.webp)

*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.](https://iamops.dev/media/mcp-server-no-token-passthrough/04-call.webp)

*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.](https://iamops.dev/media/mcp-server-no-token-passthrough/06-passthrough.webp)

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

### Paso 1: Instala 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

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

**Salida esperada**

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

### Paso 2: Escribe 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

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

**Salida esperada**

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

### Paso 3: Llama 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

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

**Salida esperada**

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

### Paso 4: Llama 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

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

**Salida esperada**

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

### Paso 5: Prueba 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

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

**Salida esperada**

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

### Paso 6: Limpieza

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

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

**Salida esperada**

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