Autorizar clientes con OAuth
Unos 37 minutos de lectura, con 7 ejemplos en 9 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.14. Lee el original
En esta página
- Encontrar el servidor de autorización a partir del recurso
- Identify the client with a metadata document
- Obtener un token con PKCE
- Vincula cada token a un solo servidor
- Valida el emisor de cada respuesta
- Delimita las herramientas según lo que permite el token
- Ask for more scope when a call needs it
- Lo que sale mal en producción
- Decisiones que tomó este capítulo
Al final de este capítulo podrás proteger el servidor del Model Context Protocol de la tienda con OAuth. Publicarás los metadatos que llevan al cliente al servidor de autorización, identificarás el host del equipo de soporte con un Client ID Metadata Document, obtendrás tokens con PKCE, aceptarás solo los tokens emitidos para el servidor de la tienda, detectarás un ataque de confusión de servidores de autorización (mix-up) mediante el emisor de cada respuesta, y exigirás un scope por herramienta, con step-up cuando un reembolso necesite más. Sus afirmaciones son las de la especificación en la revisión 2026-07-28, tal como la implementa mcp 2.3.0, el SDK de Python.
Servir sobre Streamable HTTP trasladó a shop-support, el servidor a través del cual el personal de soporte de la tienda consulta pedidos y emite reembolsos, a una dirección HTTP para que sus hosts pudieran compartirlo. Su comprobación de Origin solo filtra páginas web y nada más: cualquier programa que llegue al puerto puede leer pedidos y emitir reembolsos (Rechazar solicitudes de otros orígenes). Por eso la tienda necesita saber qué host llama, en nombre de qué persona y qué puede hacer esa persona. El personal de soporte puede consultar pedidos y existencias; solo una persona responsable de soporte puede emitir reembolsos.
El Model Context Protocol (MCP) responde con OAuth 2.1. La autorización es opcional en MCP y pertenece a los transportes HTTP; un servidor stdio toma sus credenciales del entorno en su lugar (autorización). Un servidor MCP protegido es un servidor de recursos OAuth, el cliente del host para él es un cliente OAuth, y un servidor de autorización emite los tokens, ya sea junto al servidor MCP o por separado. Conoces este flujo desde el lado del cliente de otras APIs. Lo que cambia con MCP es que un cliente no conoce de antemano a un servidor. Parte de una URL, así que el descubrimiento, la identidad del cliente y la audiencia del token tienen que funcionar sin configuración previa entre ambos.
Cuatro módulos compartidos en examples/lib/ contienen la configuración de este capítulo, de modo que cada ejemplo muestra solo su idea:
lib.auth_serveres el servidor de autorización de la tienda, en loopback: metadatos, el flujo de código de autorización con PKCE,issen todas las respuestas, y tokens de acceso JWT vinculados a un solo servidor. El consentimiento está guionizado y sustituye a la persona ante el navegador. Es un servidor didáctico para estos ejemplos en loopback, y nunca debes desplegarlo. No autentica a nadie, y su clave de firma deriva de la semilla pública del libro, así que cualquiera que tenga el libro puede acuñar tokens que este servidor acepta. Un despliegue usa un servidor de autorización consolidado que cumpla las comprobaciones de este capítulo. El SDK de Python tiene un servidor de autorización propio, pero su documentación desaconseja usarlo en servidores nuevos, y sus metadatos no anuncianissni Client ID Metadata Documents (documentación de autorización del SDK).lib.oauth_clientes el lado del host: elOAuthClientProviderdel SDK con almacenamiento de tokens en memoria, y un navegador guionizado que sigue las redirecciones del servidor de autorización y devuelve la respuesta al SDK.lib.tool_scopesañade la comprobación de scope por herramienta que el SDK no tiene.lib.protected_shoplos reúne: las cinco herramientas del capítulo 3 tras OAuth, tal como las deja este capítulo.
Todo se ejecuta en 127.0.0.1 sobre HTTP simple. Eso es aceptable solo para desarrollo local. En producción, todo endpoint del servidor de autorización DEBE servirse sobre HTTPS (consideraciones de seguridad).
Encontrar el servidor de autorización a partir del recurso
Un cliente que solo tiene la URL de un servidor debe averiguar en el propio servidor dónde obtener un token, y la revisión fijada lo hace en dos pasos. Primero, los servidores MCP DEBEN publicar los metadatos del recurso protegido (RFC 9728), un documento JSON que nombra el recurso y enumera al menos un servidor de autorización (authorization). Una solicitud sin token recibe un 401, y su encabezado WWW-Authenticate apunta a ese documento mediante un parámetro resource_metadata. Un cliente que no encuentra ese parámetro prueba la URI well-known, /.well-known/oauth-protected-resource con la ruta del servidor insertada, y después sin la ruta (descubrimiento del servidor de autorización). Segundo, el cliente obtiene los metadatos propios del servidor de autorización (RFC 8414), que enumeran sus endpoints y lo que soporta.
Dos valores deben coincidir durante el proceso. El resource de los metadatos del servidor debe ser idéntico a la URL que usó el cliente, o el cliente no debe usar esos metadatos (RFC 9728, sección 3.3). Y el issuer de los metadatos del servidor de autorización debe ser idéntico al emisor a partir del cual el cliente construyó la URL well-known (RFC 8414, sección 3.3). Ambas comprobaciones impiden que un cliente confíe en un documento que describe otro servidor.
El servidor de la tienda declara su propia URL, y el servidor de autorización declara su emisor. El SDK hace la mitad del servidor cuando le das a MCPServer un AuthSettings y un verificador de tokens: issuer_url nombra el servidor de autorización, resource_server_url es la URL del endpoint del propio servidor, y required_scopes enumera los ámbitos que necesita cada solicitud. El servidor de la tienda requiere orders:read y stock:read, porque cada ticket necesita uno o ambos. refunds:write llega más adelante, y solo cuando un reembolso lo necesita. El verificador de tokens es lib.auth_server.JwtVerifier, que comprueba la firma, el emisor y la caducidad de un token. En loopback el puerto, y por tanto la URL del recurso, solo se conoce una vez abierto el socket. Por eso el servidor se construye en una función de su URL base, y serve_built de lib.auth_server abre primero el socket. Después el ejemplo hace de cliente: envía tools/list sin token y sigue la respuesta.
1"""Protect the shop's server with OAuth, then follow its 401 to the authorization server, as a client does. The point2rests on the challenge's error line and on the PKCE methods line; the asserts check the rest of the chain."""3from urllib.parse import urlsplit45import httpx26from mcp.server.auth.settings import AuthSettings78from lib import auth_server, http_mcp, shop_tools91011def protected(issuer: str):12 def build(base_url: str): # the server must know its own URL: the resource13 settings = AuthSettings(issuer_url=issuer, resource_server_url=base_url + "/mcp",14 required_scopes=["orders:read", "stock:read"], validate_token_resource=True)15 verifier = auth_server.JwtVerifier(issuer)16 return shop_tools.create_server(version="0.8.0", auth=settings, token_verifier=verifier).streamable_http_app()17 return build181920with auth_server.serve() as issuer, auth_server.serve_built(protected(issuer.url)) as base_url: # the socket opens before the app is built, so the app knows its URL21 first = http_mcp.post(base_url + "/mcp", "tools/list") # no token22 print("status:", first.status_code)23 # [7:] drops the scheme, "Bearer ", which is 7 characters; the values that follow are quoted24 challenge = dict(part.split("=", 1) for part in first.headers["www-authenticate"][7:].split(", "))25 print("challenge parameters:", ", ".join(challenge))26 print("challenge error:", challenge["error"].strip('"'))27 metadata_url = challenge["resource_metadata"].strip('"')28 print("resource metadata path:", urlsplit(metadata_url).path)29 resource = httpx2.get(metadata_url).json()30 assert resource["resource"] == base_url + "/mcp" # RFC 9728: the endpoint's own URL31 print("authorization servers:", len(resource["authorization_servers"]))32 print("scopes_supported:", " ".join(resource["scopes_supported"]))33 found = resource["authorization_servers"][0] # the one server the metadata lists34 metadata = httpx2.get(found + "/.well-known/oauth-authorization-server").json()35 assert metadata["issuer"] == found # RFC 8414: the URL it was fetched from36 print("code_challenge_methods_supported:", metadata["code_challenge_methods_supported"])37 assert metadata["client_id_metadata_document_supported"] # the server advertises metadata documents38 assert metadata["authorization_response_iss_parameter_supported"] # and iss on every authorization response
python discover-the-authorization-server.pystatus: 401
challenge parameters: error, error_description, resource_metadata
challenge error: invalid_token
resource metadata path: /.well-known/oauth-protected-resource/mcp
authorization servers: 1
scopes_supported: orders:read stock:read
code_challenge_methods_supported: ['S256']
La primera solicitud obtuvo 401, con un desafío que contiene error, error_description, resource_metadata y el error invalid_token. Ese error es una decisión del SDK, y una desviación de RFC 6750, que dice que un servidor NO DEBERÍA incluir un código de error cuando una solicitud no lleva credenciales en absoluto (RFC 6750, sección 3.1).
La ruta de la URL de metadatos es /.well-known/oauth-protected-resource/mcp, el prefijo well-known con la ruta del servidor insertada, como pide RFC 9728. Los metadatos nombran la URL propia del endpoint como su recurso, enumeran 1 servidor de autorización, y dan scopes_supported como orders:read stock:read, que el SDK rellena a partir de required_scopes.
El desafío no tiene un parámetro scope, porque el 401 del SDK nunca envía uno (mcp/server/auth/middleware/bearer_auth.py). Así que un cliente recurre a scopes_supported. El orden de la especificación es primero el scope del desafío, después cada ámbito de scopes_supported, y después ningún scope en absoluto (authorization). Por eso scopes_supported debe ser el conjunto más pequeño que funcione, no todos los ámbitos que conoce el servidor: sea lo que sea lo que enumere, cada host lo pide a cada usuario.
Los metadatos del servidor de autorización nombran la URL desde la que el cliente los obtuvo como su emisor, y declaran tres cosas en las que se apoya el resto del capítulo: métodos PKCE ['S256'], soporte para Client ID Metadata Documents, y iss en las respuestas de autorización. El cliente del SDK hace ambas comprobaciones de coincidencia por ti. Lanza OAuthFlowError cuando el issuer de los metadatos difiere del esperado, comparado como cadenas simples (guía de migración del SDK). Su comprobación del recurso es más laxa que RFC 9728: acepta metadatos cuyo resource es un prefijo de ruta del mismo origen de la URL del servidor (mcp/shared/auth_utils.py). Un callback validate_resource_url en OAuthClientProvider reemplaza esa comprobación por la tuya.
Regla práctica: Da a cada servidor protegido un AuthSettings con la URL de su endpoint como resource_server_url, exactamente como la escribirán los clientes, y el required_scopes más pequeño que necesita cada solicitud. Comprueba la cadena con una solicitud que no lleve token: un 401, una URL de resource_metadata, unos metadatos cuyo resource sea el endpoint, y unos metadatos del servidor de autorización cuyo issuer sea la URL desde la que los obtuviste. Cuando un valor difiera por una barra final o un puerto, corrige la configuración en lugar de relajar el cliente.
Esta parte aún no está traducida, así que está en inglés.
Identify the client with a metadata document
Find the authorization server from the resource tells the host where to get a token. The authorization server still has to know which client is asking, and a host meets MCP servers it has never seen, so it can't have registered with each one's authorization server in advance. The pinned revision ranks the ways to get a client ID. Pre-registered client information comes first, if there is any. A Client ID Metadata Document comes next, if the authorization server advertises client_id_metadata_document_supported. Dynamic Client Registration follows, and the user is asked only when none of these is available (client registration).
A Client ID Metadata Document makes the client ID a URL. The client publishes a JSON document at an https:// URL with a path, and that URL is its client_id. The document must contain at least client_id, equal to the URL exactly, client_name and redirect_uris (client registration). The authorization server fetches the document when the client first appears, checks the ID and the redirect URI against it, and may cache it by its HTTP headers. It must not follow redirects while fetching, and it must not cache an error (metadata document draft -02).
A document can't carry a shared secret, because client_secret is forbidden. A client identified this way is therefore public, and it relies on PKCE, or proves itself with a key pair through private_key_jwt (draft -02, section 4.1). The MCP specification links draft -00 of that document, and we cite draft -02, the later text. A client ID from a document works with any authorization server. A pre-registered or registered client ID, by contrast, is bound to the server that issued it, and the pinned revision forbids reusing it with another (client registration).
Dynamic Client Registration is deprecated at the pinned revision. It stays as a fallback for authorization servers without metadata document support, and its earliest removal is the first revision released on or after 2027-07-28 (deprecated features). Replace dynamic client registration moves a client off it.
The support team's host publishes its document at https://support.fernhill.example/oauth/client.json. Nothing here reaches a network, and fernhill.example never resolves, so the shop's authorization server can't fetch it. Rather than give the host an http:// client ID that a loopback server could fetch, lib.auth_server keeps the document in a mapping from client ID URL to document. That mapping stands in for the fetch, and the server applies to it the checks it would apply to a fetched copy. This is pre-registration of the URL, which the draft allows as associating a client ID URL with its metadata "through other means" (draft -02, section 5). It is a test-only stand-in, and a deployed authorization server fetches the document over HTTPS.
The code prints the document's key values, runs the server's checks on it and on three broken copies, gives the SDK an http:// client ID, and then connects twice, to an authorization server that supports metadata documents and to one that doesn't.
1"""The support host's Client ID Metadata Document, the checks an authorization server makes on it, and the SDK's client2sending its URL as the client ID, with and without the authorization server's support. The point rests on the3`client_id sent` line and on the fallback's error line, which show what the SDK did in each case."""4import asyncio56from mcp.client.auth import OAuthRegistrationError78from lib import auth_server, oauth_client, protected_shop910document = auth_server.client_document() # served at auth_server.CLIENT_ID11print("client_id:", document["client_id"])12print("redirect_uris:", ", ".join(document["redirect_uris"]))13print("token_endpoint_auth_method:", document["token_endpoint_auth_method"])14for label, url, candidate in [15 ("as published", auth_server.CLIENT_ID, document),16 ("with a secret", auth_server.CLIENT_ID, auth_server.client_document(client_secret="not-a-secret")),17 ("another client_id", auth_server.CLIENT_ID, auth_server.client_document(client_id="https://partner.example/")),18 ("on http", "http://support.fernhill.example/oauth/client.json", document)]:19 print(f"document {label}:", auth_server.document_problem(url, candidate) or "accepted")20try:21 oauth_client.provider("http://127.0.0.1/mcp", browser=oauth_client.ScriptedBrowser(),22 client_metadata_url="http://localhost:4280/client.json") # the SDK checks the scheme when it's built23except ValueError:24 print("SDK given an http client ID: ValueError")252627async def connect(**server_options) -> None:28 with auth_server.serve(**server_options) as issuer, protected_shop.serve(issuer.url) as url:29 browser = oauth_client.ScriptedBrowser()30 try:31 async with oauth_client.connect(url, browser=browser) as client:32 await client.list_tools()33 print("client_id sent:", browser.requests[0]["client_id"])34 except* OAuthRegistrationError as group: # the SDK fell back to registration35 print("without metadata document support:", group.exceptions[0])363738asyncio.run(connect()) # the shop's server advertises metadata document support39asyncio.run(connect(advertise_cimd=False)) # a server that doesn't, so the SDK registers instead
python publish-client-metadata.pyclient_id: https://support.fernhill.example/oauth/client.json
redirect_uris: http://localhost:4280/callback
token_endpoint_auth_method: none
document as published: accepted
document with a secret: document carries a shared secret
document another client_id: document client_id differs from its URL
document on http: client_id must be an https URL with a path
SDK given an http client ID: ValueError
client_id sent: https://support.fernhill.example/oauth/client.json
without metadata document support: Registration failed: 404 Not Found
The document names https://support.fernhill.example/oauth/client.json as its own ID, and its redirect URI is http://localhost:4280/callback. Its token endpoint authentication method is none, so the host holds no secret. The authorization server accepts the document as published.
A copy with a secret fails with "document carries a shared secret", and the other two broken copies fail for the reasons printed beside them: one whose client_id names another site, and one whose client ID is on http. The SDK makes the same https check on its side. Given an http:// client ID, OAuthClientProvider raises ValueError as soon as it is built (mcp/client/auth/utils.py).
The SDK's client uses the document's URL as its client ID, and it falls back quietly when the server doesn't support that. Against the shop's authorization server it sent https://support.fernhill.example/oauth/client.json as the client ID, and made no registration request. Against a server that doesn't advertise support, it fell back to Dynamic Client Registration without a word, and the flow ended with "Registration failed: 404 Not Found", because the shop's authorization server has no registration endpoint. The SDK's documentation calls this fallback silent (OAuth clients). For the host, an authorization server without metadata document support shows up as a registration error, not as a missing feature.
Working rule: Give every host one Client ID Metadata Document at a stable https:// URL, with only the redirect URIs it uses and no secret, and pass that URL to the SDK as client_metadata_url. Use pre-registered credentials where an authorization server has issued them, since they rank first, and keep Dynamic Client Registration only for authorization servers that support nothing else. In tests on loopback, keep the client ID an https:// URL and associate it with a local copy of the document in the test authorization server, rather than giving the client an http:// ID that no production server accepts.
Obtener un token con PKCE
Con su ID de cliente de Identificar el cliente con un documento de metadatos, el host puede pedir un token. MCP usa el flujo de código de autorización. El host envía el navegador del usuario al endpoint de autorización del servidor de autorización, el usuario inicia sesión y da su consentimiento, y el navegador regresa al URI de redirección del host con un código. Luego el host intercambia ese código por un token en el endpoint de token. Tres parámetros de ese intercambio sostienen la mayor parte de su seguridad.
PKCE vincula el código al cliente que lo pidió. El cliente genera un code_verifier aleatorio, envía su hash SHA-256 como code_challenge con code_challenge_method=S256, y revela el verificador solo en la solicitud de token, de modo que quien intercepte el código no lo tiene. Los clientes MCP DEBEN usar PKCE con S256, y DEBEN negarse a continuar si los metadatos del servidor de autorización no tienen code_challenge_methods_supported (consideraciones de seguridad). OAuth 2.1 ha prohibido explícitamente el método plain, en el que el desafío es el propio verificador, desde el draft-16 (OAuth 2.1 draft-16, sección 7.5.2). La especificación de MCP cita el draft-13, que todavía lo permitía (OAuth 2.1 draft-13).
El parámetro resource (RFC 8707) indica el servidor para el que es el token, mediante la URI canónica del servidor. Los clientes MCP DEBEN enviarlo tanto en la solicitud de autorización como en la solicitud de token, tanto si el servidor de autorización lo admite como si no (autorización). Y state, que el cliente comprueba cuando el navegador regresa, vincula la respuesta a la solicitud.
El cliente del SDK ejecuta para el host todo ese flujo, y el ejemplo lo observa desde el lado del servidor de autorización. lib.oauth_client.connect da al cliente un OAuthClientProvider con la URL del documento de metadatos del host y un navegador automatizado en lugar de una persona. El navegador abre la URL de autorización, sigue las redirecciones y se detiene en la primera dirigida al URI de redirección. El consentimiento de la persona en el servidor de autorización también está automatizado: el usuario que inició sesión concede cada ámbito solicitado que su rol permite. El ejemplo llama a get_order_status, lee lo que el servidor de autorización registró y después envía al servidor de autorización tres solicitudes que el SDK nunca enviaría.
1"""The SDK's client gets a token for the shop's server with the authorization code grant, PKCE S256 and the resource2parameter, then the authorization server refuses a code sent twice, a wrong verifier and the plain method. The point3rests on the status line, the refusals at the end, and the asserts that check the challenge, the resource and the token."""4import asyncio5import os67import httpx289from lib import auth_server, loopback, oauth_client, protected_shop, shop_api101112async def main() -> None:13 with auth_server.serve() as issuer, loopback.serve(shop_api.create_app()) as api_url:14 os.environ.update(shop_api.server_env(api_url)) # the server runs in this process15 with protected_shop.serve(issuer.url) as url:16 browser, storage = oauth_client.ScriptedBrowser(), oauth_client.MemoryStorage()17 async with oauth_client.connect(url, browser=browser, storage=storage) as client:18 result = await client.call_tool("get_order_status", {"order_id": "O-1873"})19 print("O-1873 status:", result.structured_content["status"])20 asked, exchanged = issuer.events # /authorize, then /token21 print("authorization request:", ", ".join(key for key in asked if key != "endpoint"))22 print("code_challenge_method:", asked["code_challenge_method"])23 # the challenge is the hash of the verifier that the token request revealed24 assert oauth_client.s256(exchanged["code_verifier"]) == asked["code_challenge"]25 assert asked["resource"] == exchanged["resource"] == url # the server's URL, in both requests26 claims = auth_server.claims(storage.tokens.access_token)27 for claim, expected in [("aud", url), ("iss", issuer.url)]: # the server; the issuer28 assert claims[claim] == expected, claim29 print("token sub:", claims["sub"])30 print("token scope:", claims["scope"])31 print("refresh token:", storage.tokens.refresh_token)32 again = httpx2.post(issuer.url + "/token", data=exchanged) # the same code a second time33 print("code sent twice:", again.status_code, again.json()["error"])34 # the challenge is the hash of a verifier this example knows, so the guessed one is the only thing wrong35 code = oauth_client.authorize_by_hand(issuer.url, url, challenge=oauth_client.s256("the-real-verifier"))36 stolen = {**exchanged, "code": code["code"], "code_verifier": "a-guessed-verifier"}37 print("wrong verifier:", httpx2.post(issuer.url + "/token", data=stolen).json()["error"])38 # method="plain" sends the verifier itself as the challenge, which OAuth 2.1 forbids39 plain = oauth_client.authorize_by_hand(issuer.url, url, challenge="the-real-verifier", method="plain")40 print("plain method:", plain["error"], "/", plain["error_description"])414243asyncio.run(main())
python token-with-pkce.pyO-1873 status: delivered
authorization request: response_type, client_id, redirect_uri, state, code_challenge, code_challenge_method, resource, scope
code_challenge_method: S256
token sub: staff-0007
token scope: orders:read stock:read
refresh token: None
code sent twice: 400 invalid_grant
wrong verifier: invalid_grant
plain method: invalid_request / PKCE with S256 is required
La llamada funcionó, y el pedido O-1873 es delivered. La solicitud de autorización llevó response_type, client_id, redirect_uri, state, code_challenge, code_challenge_method, resource, scope, con el método S256, y su desafío es el hash del verificador que la solicitud de token reveló. Ambas solicitudes indicaron el mismo recurso, la URL del endpoint. El token de acceso es un JWT cuyo aud es la URL del servidor y cuyo iss es el servidor de autorización. Su ámbito es orders:read stock:read, el scopes_supported del servidor, porque el 401 no nombró ningún ámbito.
El sub del token, staff-0007, nombra al miembro del equipo de soporte en nombre del cual actúa el host, no a un cliente, y un servidor lo lee del get_access_token().subject del SDK. Así, un token de personal no puede por sí solo sustituir a SHOP_CUSTOMER_ID, que la finalización del pedido en Completar argumentos para el usuario leía de su entorno mediante stdio. Para un host de soporte, el cliente procede del registro del ticket en el que trabaja el miembro del personal, que el servidor busca y verifica, nunca de un argumento de la herramienta. Solo donde los clientes inician sesión en un host por sí mismos, sub es el cliente, el caso que trata Evitar que el servidor actúe como un diputado confundido. No hay token de actualización (None): el servidor de autorización de la tienda no emite ninguno, y la especificación indica a los clientes que no den por hecho que exista (autorización).
Las tres solicitudes que el SDK nunca envía muestran lo que PKCE y los códigos de un solo uso impiden. El mismo código enviado por segunda vez obtuvo 400 invalid_grant, porque un código funciona una sola vez. Un código nuevo enviado con un verificador adivinado obtuvo invalid_grant, de modo que un código robado por sí solo no sirve de nada. Una solicitud con plain obtuvo "invalid_request / PKCE with S256 is required", porque el servidor de autorización de la tienda solo acepta S256.
Una comprobación queda en manos del host. El cliente del SDK siempre envía S256, pero nunca lee code_challenge_methods_supported, así que continúa con un servidor de autorización cuyos metadatos omiten ese campo (mcp/client/auth/oauth2.py). Un host que debe cumplir la especificación obtiene él mismo los metadatos de cada servidor de autorización antes de conectarse, y rechaza cualquier servidor que no liste S256.
Regla práctica: Deja que el OAuthClientProvider del SDK ejecute el flujo de código de autorización, y comprueba una vez, desde el lado del servidor de autorización, qué envía: S256, state, y un resource igual a la URL del servidor en ambas solicitudes. Añade la comprobación que el SDK omite, y rechaza un servidor de autorización cuyos metadatos no listen S256. En un servidor de autorización que administres, acepta solo S256, haz que los códigos sean de un solo uso y de corta duración, y vincula cada código a su cliente, a su URI de redirección y a su recurso.
Vincula cada token a un solo servidor
El token de Obtén un token con PKCE nombra el servidor de la tienda en aud, porque el host envió resource. Eso no protege a nadie a menos que el servidor lo compruebe. Un token de acceso es una credencial de portador, así que quien lo tenga puede presentarlo. Supón que el host de soporte también se conecta a un servidor MCP de un socio que confía en el mismo servidor de autorización. El servidor del socio recibe los tokens que el host obtiene para él. Si el servidor de la tienda los aceptara, el operador del socio podría reproducirlos contra la tienda. RFC 8707 indica que el servidor de autorización DEBERÍA restringir la audiencia de cada token al recurso solicitado, de modo que un token "presentado legítimamente a un recurso no pueda luego ser tomado por ese recurso y presentado en otro lugar" (RFC 8707). La otra mitad corresponde al servidor: los servidores MCP DEBEN validar que un token fue emitido para ellos como audiencia, y NO DEBEN aceptar ni reenviar ningún otro token (autorización).
En el SDK de Python en mcp 2.3.0, la mitad que corresponde al servidor está desactivada por defecto. AuthSettings.validate_token_resource decide si el servidor rechaza un token cuyo AccessToken.resource no sea resource_server_url. Si no se define, emite una advertencia con MCPDeprecationWarning y se comporta como False, y la versión 3.0 hace de True el valor por defecto (mcp/server/auth/settings.py). El SDK compara ambos valores como URL. Las mayúsculas y minúsculas del esquema y del host, un puerto por defecto o una barra final no influyen (mcp/server/auth/middleware/bearer_auth.py), y la comparación usa lo que tu verificador de tokens coloque en AccessToken.resource. La otra vía es un verificador que comprueba aud por sí mismo.
Dos tokens muestran qué comprobación hace el trabajo. El ejemplo firma ambos con la clave del servidor de autorización de la tienda, uno para el servidor de la tienda y otro para el del socio, https://partner.example/mcp, y los presenta al servidor de la tienda en tres configuraciones: el valor por defecto del SDK, validate_token_resource=True, y un verificador que pasa la URL de la tienda a la biblioteca JWT como audiencia esperada.
1"""A token issued for another server, presented to the shop's server: the SDK's default accepts it, and it's refused once2the server checks the audience, either through AuthSettings or in the token verifier. The point rests on the partner's3token's status line in each configuration, and on the warning line that the default alone raises."""4import warnings56from mcp.server.auth.settings import AuthSettings78from lib import auth_server, http_mcp, shop_tools910PARTNER = "https://partner.example/mcp" # another MCP server, with the same authorization server11SCOPES = ["orders:read", "stock:read"]121314def shop(issuer: str, validate_token_resource: bool | None, verifier_checks_aud: bool):15 def build(base_url: str):16 resource = base_url + "/mcp"17 # the verifier checks aud only when it's given an audience; None checks nothing18 verifier = auth_server.JwtVerifier(issuer, audience=resource if verifier_checks_aud else None)19 # None leaves the SDK's default in place, which is off and warns; True refuses other servers' tokens20 settings = AuthSettings(issuer_url=issuer, resource_server_url=resource, required_scopes=SCOPES,21 validate_token_resource=validate_token_resource)22 return shop_tools.create_server(auth=settings, token_verifier=verifier).streamable_http_app()23 return build242526with auth_server.serve() as issuer:27 for label, validate, in_verifier in [("SDK default", None, False), ("validate_token_resource=True", True, False),28 ("verifier checks aud", False, True)]:29 # record every warning, and show them all, so each configuration reports only what it raised30 with warnings.catch_warnings(record=True) as caught:31 warnings.simplefilter("always")32 with auth_server.serve_built(shop(issuer.url, validate, in_verifier)) as base_url:33 url = base_url + "/mcp"34 own = auth_server.mint(issuer.url, url, SCOPES)35 foreign = auth_server.mint(issuer.url, PARTNER, SCOPES) # signed by the same authorization server36 for name, token in [("own token", own), ("partner's token", foreign)]:37 response = http_mcp.post(url, "tools/list", headers={"Authorization": f"Bearer {token}"})38 print(f"{label}, {name}:", response.status_code)39 print(f"{label}, warnings:", ", ".join(sorted({w.category.__name__ for w in caught})) or "none")
python wrong-audience-rejected.pySDK default, own token: 200
SDK default, partner's token: 200
SDK default, warnings: MCPDeprecationWarning
validate_token_resource=True, own token: 200
validate_token_resource=True, partner's token: 401
validate_token_resource=True, warnings: none
verifier checks aud, own token: 200
verifier checks aud, partner's token: 401
verifier checks aud, warnings: none
Con el valor por defecto del SDK, el token del socio obtuvo 200, y el servidor enumeró sus herramientas para un token emitido a otra persona. La única señal fue una advertencia al arrancar, MCPDeprecationWarning. Cualquiera de las dos comprobaciones rechaza el token del socio. Con validate_token_resource=True obtuvo 401, y con la comprobación de audiencia en el verificador obtuvo 401. Ambos rechazos son 401 con invalid_token, la respuesta que la especificación da a un token que no es válido para el servidor. El token propio de la tienda fue aceptado en las tres configuraciones, y ninguna de las dos correcciones emitió advertencias.
Recomendamos validate_token_resource=True, que lib.protected_shop establece. Deja la decisión registrada junto a los demás ajustes de autorización del servidor, y sobrevive a un cambio de verificador de tokens. Comprueba también aud en el verificador cuando el verificador decodifique el token de todos modos, ya que la segunda comprobación no tiene coste.
Regla práctica: Define validate_token_resource=True en cada servidor protegido, y haz que el verificador de tokens complete AccessToken.resource a partir del aud del token. Trata un MCPDeprecationWarning proveniente de AuthSettings como un despliegue fallido, no como ruido. Prueba la comprobación con un token para otro recurso del mismo servidor de autorización, que debe obtener 401. Un servidor que llama a otro servicio en nombre de un cliente obtiene su propio token para ese servicio y nunca reenvía el token del cliente (Nunca reenvíes el token de un cliente).
Valida el emisor de cada respuesta
Vincular la audiencia, como hace Vincula cada token a un solo servidor, impide que un token funcione en el servidor equivocado. Un ataque de mix-up actúa antes, sobre el código de autorización. Un host que se comunica con varios servidores de autorización envía cada código al servidor que cree que respondió. En un mix-up, el servidor de autorización del atacante hace que el host inicie un flujo con él y después envía el navegador del usuario a un servidor de autorización legítimo. El código del servidor legítimo llega al URI de redirección del host. El host, que sigue creyendo que habla con el atacante, envía el código al endpoint de token del atacante. PKCE por sí solo no lo evita, "porque el cliente transmite el code_verifier al endpoint de token del atacante" (mejores prácticas de seguridad). Tampoco lo evita resource, que el atacante reescribe en la solicitud que reenvía.
La defensa es el parámetro iss de RFC 9207. El servidor de autorización se identifica en su redirección, y el cliente compara ese nombre con el servidor al que envió al usuario. La revisión fijada introdujo esta comprobación (registro de cambios). Antes de redirigir, el cliente registra el emisor de los metadatos validados del servidor de autorización, y compara iss con ese registro mediante una comparación exacta de cadenas, sin normalizar mayúsculas, puertos ni barras (autorización).
Las reglas son condicionales. Los servidores de autorización DEBERÍAN incluir iss, y el que lo haga DEBE anunciar authorization_response_iss_parameter_supported. Un cliente DEBE comparar un iss presente, independientemente de lo que digan los metadatos, y DEBE rechazar una respuesta sin iss solo cuando el servidor haya anunciado soporte. En caso contrario, continúa. Ante una discrepancia, el cliente no debe actuar sobre ningún error de la respuesta ni mostrarlo. La especificación prevé que una revisión posterior convierta iss en un DEBE para los servidores de autorización (autorización). Comparar un iss presente que no fue anunciado usa la libertad que RFC 9207 deja a la política local, y su valor por defecto es que los clientes DEBERÍAN descartar esa respuesta (RFC 9207, sección 2.4).
El atacante del caso de la tienda es el socio, y MixUp de lib.auth_server lo interpreta. El servidor MCP del socio nombra al servidor de autorización del atacante, que copia los metadatos del servidor de autorización de la tienda sin soporte de iss. Su endpoint de autorización reenvía el navegador al servidor de autorización de la tienda, llevando la solicitud propia del host reescrita para pedir el servidor de la tienda y todos los scopes. El identificador de cliente del host es una URL de documento de metadatos, que funciona con cualquier servidor de autorización, de modo que el servidor de autorización de la tienda ve una solicitud procedente del host real de soporte.
1"""A mix-up attack on the support host, run against a shop server that sends `iss` and one that omits it. The point rests2on the codes-received lines: the `iss` mismatch leaves the attacker nothing, and without `iss` it gets a token."""3import asyncio45from mcp.client.auth import OAuthFlowError, OAuthTokenError67from lib import auth_server, oauth_client, protected_shop8910async def attempt(label: str, **shop_options) -> None:11 with auth_server.serve(**shop_options) as shop_issuer, protected_shop.serve(shop_issuer.url) as shop_url:12 # the attacker's server forwards the browser to the shop's, and the partner's server names the attacker13 with auth_server.serve_mix_up(shop_issuer.url, target=shop_url) as attacker, \14 protected_shop.serve(attacker.url) as partner_url:15 browser = oauth_client.ScriptedBrowser()16 try:17 async with oauth_client.connect(partner_url, browser=browser) as client:18 await client.list_tools()19 except* (OAuthFlowError, OAuthTokenError) as group:20 error = group.exceptions[0]21 print(f"{label}, host stopped:", type(error).__name__, str(error).split(":")[0]) # the message's first phrase22 assert "code" in browser.arrived # the user consented at the shop's server23 print(f"{label}, iss in the answer:", "shop's" if browser.arrived.get("iss") == shop_issuer.url else "none")24 print(f"{label}, codes the attacker received:", len(attacker.stolen))25 for loot in attacker.stolen:26 claims = auth_server.claims(loot["access_token"])27 assert claims["aud"] == shop_url # the token names the shop's server as its audience28 print(f"{label}, attacker's token scope:", claims["scope"])293031asyncio.run(attempt("shop sends iss"))32asyncio.run(attempt("shop omits iss", send_iss=False, advertise_iss=False))
python mix-up-attack-blocked.pyshop sends iss, host stopped: OAuthFlowError Authorization response iss mismatch
shop sends iss, iss in the answer: shop's
shop sends iss, codes the attacker received: 0
shop omits iss, host stopped: OAuthTokenError Token exchange failed (400)
shop omits iss, iss in the answer: none
shop omits iss, codes the attacker received: 1
shop omits iss, attacker's token scope: orders:read stock:read refunds:write
El ataque se ejecuta dos veces, contra un servidor de autorización de la tienda que envía iss y contra otro que no lo envía, y cada ejecución muestra lo que vio el host y lo que obtuvo el atacante. En ambas ejecuciones el usuario dio su consentimiento en el servidor de autorización de la tienda, porque la solicitud que tenía delante procedía del host real de soporte. Cuando la tienda envía iss, la respuesta llevaba el emisor shop's, el SDK se detuvo con OAuthFlowError Authorization response iss mismatch, y el atacante recibió 0 códigos.
Cuando la tienda omite iss, la respuesta llevaba none, y el SDK continuó, como indica la especificación que debe hacer con un servidor que nunca anunció iss. El atacante recibió 1 código con su verificador, lo canjeó en el servidor de autorización de la tienda y posee un token para el servidor de la tienda con el scope orders:read stock:read refunds:write, que incluye los reembolsos. El host solo vio OAuthTokenError Token exchange failed (400).
Por tanto, la comprobación protege a un host solo cuando el servidor legítimo envía iss. Las mejores prácticas de seguridad indican que la comprobación no ofrece protección frente a un servidor legítimo que omite iss (mejores prácticas de seguridad). El SDK sigue exactamente la tabla de la especificación (validate_authorization_response_iss en mcp/client/auth/utils.py). Que los tokens de la tienda puedan robarse de este modo depende, por tanto, del servidor de autorización de la tienda, no del host. La otra defensa que describe RFC 9700, un URI de redirección distinto para cada servidor de autorización, no ayuda a este host. RFC 9700 dice que "no puede usarse en escenarios donde los clientes se registran una sola vez para el uso de muchos emisores diferentes", y que debe usarse solo cuando no hay otra opción (RFC 9700, sección 4.4.2.2). Un cliente identificado por un documento de metadatos es ese caso, con un único client_id y una sola lista de URI de redirección para todos los servidores de autorización, de modo que el servidor legítimo acepta cualquier URI de la lista que reenvíe el atacante. Lo que un host puede hacer sin ayuda del servidor es limitar qué servidores de autorización utiliza. El servidor del atacante, si no figura en la lista de permitidos del host, nunca inicia un flujo.
Regla práctica: Envía iss desde cada servidor de autorización que gestiones, y anúncialo con authorization_response_iss_parameter_supported: true, de modo que los clientes rechacen una respuesta que no lo incluya. En un host, conserva la comprobación del SDK, no añadas normalización a su alrededor y trata una discrepancia como un ataque: no muestres al usuario ningún texto de error de esa respuesta. Cuando un host deba usar un servidor de autorización que no envía iss, limita el host a una lista de permitidos de servidores de autorización, y rechaza o advierte al usuario sobre cualquier servidor que no figure en ella. No confíes en un URI de redirección separado por servidor cuando el host se identifica mediante un documento de metadatos.
Delimita las herramientas según lo que permite el token
Con las comprobaciones de Vincula cada token a un servidor y Valida el emisor de cada respuesta hechas, el servidor de la tienda sabe quién hace la llamada. Aun así, tiene que decidir qué puede hacer cada llamador. El token enumera los ámbitos concedidos, y la tienda tiene tres: orders:read para buscar, leer y presupuestar pedidos, stock:read para consultar el stock, y refunds:write para emitir un reembolso, que solo los responsables de soporte pueden conceder.
El SDK comprueba los ámbitos por endpoint, no por herramienta. AuthSettings.required_scopes se aplica a cada petición, y el 403 propio del SDK no nombra ningún scope (mcp/server/auth/middleware/bearer_auth.py). La especificación pide un desafío con el que un cliente pueda actuar: un 403 con WWW-Authenticate: Bearer error="insufficient_scope", el scope que necesita la operación y resource_metadata, con "todos los ámbitos requeridos para la operación actual en un único desafío" (authorization). Un middleware HTTP puede enviarlo. En la revisión fijada, cada tools/call nombra su herramienta en la cabecera Mcp-Name, pero los servidores DEBEN decodificar su forma =?base64?...?= antes de compararla con el cuerpo (Streamable HTTP). Una comprobación sobre la cabecera sin decodificar deja pasar un issue_refund codificado. Y un cliente de la revisión 2025-11-25, que el servidor del SDK sigue aceptando en el mismo endpoint, no envía ningún Mcp-Name.
Por eso lib.tool_scopes.require decide sobre lo que el servidor va a ejecutar, con la credencial que usa el SDK. Lee la herramienta desde el params.name del cuerpo ya analizado, y la cabecera Mcp-Name, decodificada como la decodifica el SDK, debe coincidir con ese nombre; si no, la petición recibe -32020, HeaderMismatch. Se rechaza un cuerpo que no sea un único objeto JSON o que repita una clave. El SDK autentica con la primera cabecera Authorization (mcp/server/auth/middleware/bearer_auth.py), así que el middleware rechaza dos de ellas con 400 invalid_request, y lee el token a través del BearerAuthBackend del SDK, respondiendo 401 a una llamada de herramienta cuyo token no se verifica.
El middleware deniega por defecto: una herramienta que falte en el mapa se rechaza. Los métodos que no nombran nada, como tools/list, solo necesitan los ámbitos del endpoint, y cualquier otro método, como prompts/get, resources/read o tasks/get, recibe 403. lib.protected_shop asigna las cinco herramientas, y lib.tool_scopes.hide_unscoped puede ocultar las herramientas que un token no puede llamar (Mantén pequeña la lista de herramientas). Con los dos ámbitos de lectura, el ejemplo lista las herramientas con la ocultación desactivada y activada, y después envía llamadas escritas a mano.
1"""The shop's server refuses a refund without `refunds:write` with a 403 challenge, decided on the parsed body rather than2on `Mcp-Name` or the first `Authorization` header, refuses methods no scope maps, and can hide the tools a token can't3call. The point rests on the 403 lines, and on the refusals a header-only check would have let through: the spellings of4`Mcp-Name`, the 2025-11-25 client, and the second header."""5import json6import os78from lib import auth_server, http_mcp, loopback, protected_shop, shop_api910REFUND = {"name": "issue_refund", "arguments": {"quote_id": "Q-00000000aa"}}11IN_BASE64 = "=?base64?aXNzdWVfcmVmdW5k?=" # "issue_refund", as the spec encodes it121314def bearer(token: str, **headers: str) -> dict[str, str]:15 return {"Authorization": f"Bearer {token}", **headers}161718with auth_server.serve() as issuer, loopback.serve(shop_api.create_app()) as api_url:19 os.environ.update(shop_api.server_env(api_url)) # the server runs in this process20 for hide in (False, True): # hiding off, then on21 with protected_shop.serve(issuer.url, hide_tools=hide) as url: # hide_tools drops the tools this token can't call22 token = auth_server.mint(issuer.url, url, ["orders:read", "stock:read"])23 listed = http_mcp.post(url, "tools/list", headers=bearer(token)).json()["result"]24 print(f"hide_tools={hide}, tools listed:", ", ".join(tool["name"] for tool in listed["tools"]))25 print("tools/list cacheScope:", listed["cacheScope"]) # the SDK's default, which suits a list that depends on the token26 with protected_shop.serve(issuer.url) as url:27 token = auth_server.mint(issuer.url, url, ["orders:read", "stock:read"])28 status = http_mcp.post(url, "tools/call", {"name": "get_order_status", "arguments": {"order_id": "O-1873"}},29 headers=bearer(token))30 print("get_order_status:", status.status_code)31 refused = http_mcp.post(url, "tools/call", REFUND, headers=bearer(token))32 print("issue_refund:", refused.status_code)33 print("challenge:", refused.headers["www-authenticate"].split(", resource_metadata")[0]) # the challenge without its URL34 assert "resource_metadata=" in refused.headers["www-authenticate"]35 # the header claims a tool the token may call, but the body asks for the refund, which the server must refuse36 lying = http_mcp.post(url, "tools/call", REFUND, headers=bearer(token, **{"Mcp-Name": "get_order_status"}))37 print("issue_refund named get_order_status in Mcp-Name:", lying.status_code, lying.json()["error"]["code"])38 encoded = http_mcp.post(url, "tools/call", REFUND, headers=bearer(token, **{"Mcp-Name": IN_BASE64}))39 print("issue_refund with Mcp-Name in base64:", encoded.status_code)40 # revision 2025-11-25 sends no Mcp-Name header at all, so the server must check the body for it41 print("issue_refund at 2025-11-25:", protected_shop.call_at_2025_11_25(url, token, REFUND).status_code)42 # two Authorization headers: the read-only token first, then junk, which the server must refuse outright43 twice = protected_shop.call_with_headers(url, REFUND, [("Authorization", f"Bearer {token}"),44 ("Authorization", "Bearer x")])45 print("issue_refund with two Authorization headers:", twice.status_code, twice.json()["error"])46 # prompts/get names a prompt, not a tool, so no scope in the map covers it and the server refuses it47 unmapped = http_mcp.post(url, "prompts/get", {"name": "review_refund"}, headers=bearer(token))48 print("prompts/get, which no scope maps:", unmapped.status_code)49 lead = auth_server.mint(issuer.url, url, ["orders:read", "stock:read", "refunds:write"])50 allowed = http_mcp.post(url, "tools/call", REFUND, headers=bearer(lead))51 print("issue_refund with a lead token:", allowed.status_code, json.loads(allowed.text)["result"]["isError"])
python refund-needs-a-scope.pyhide_tools=False, tools listed: find_orders, get_order_status, quote_refund, issue_refund, check_stock
hide_tools=True, tools listed: find_orders, get_order_status, quote_refund, check_stock
tools/list cacheScope: private
get_order_status: 200
issue_refund: 403
challenge: Bearer error="insufficient_scope", scope="refunds:write"
issue_refund named get_order_status in Mcp-Name: 400 -32020
issue_refund with Mcp-Name in base64: 403
issue_refund at 2025-11-25: 403
issue_refund with two Authorization headers: 400 invalid_request
prompts/get, which no scope maps: 403
issue_refund with a lead token: 200 True
El servidor toma el ámbito de la herramienta indicada en el cuerpo. get_order_status obtuvo 200, y issue_refund obtuvo 403, con el desafío Bearer error="insufficient_scope", scope="refunds:write". Ese desafío nombra refunds:write y lleva una URL de resource_metadata.
Con la ocultación desactivada, el token ve find_orders, get_order_status, quote_refund, issue_refund, check_stock; con la ocultación activada, find_orders, get_order_status, quote_refund, check_stock. En ambos casos el ámbito de caché de la lista es private. Es el valor por defecto del SDK, que conviene a una lista que depende del token (Almacena en caché los resultados de las listas).
Un reembolso cuyo Mcp-Name afirmaba get_order_status obtuvo 400 -32020. Dos peticiones que habría aceptado una comprobación basada solo en cabeceras fueron rechazadas por falta de ámbito. El reembolso con Mcp-Name en Base64 obtuvo 403, y el reembolso de un cliente de 2025-11-25 obtuvo 403.
Un reembolso con el token de solo lectura y una segunda cabecera Authorization basura obtuvo 400 invalid_request. Una comprobación que leyera la última cabecera habría permitido al SDK emitir el reembolso con el token de solo lectura. Un prompts/get sin asignar obtuvo 403. Con refunds:write, la llamada llegó a la herramienta, que respondió 200 True: primero el estado, luego el isError del resultado, en true porque el ID de cotización del ejemplo no existe.
Regla práctica: Asigna cada herramienta a sus ámbitos, y autoriza la petición analizada con exactamente la credencial que autentica el SDK, nunca solo por una cabecera. Rechaza dos cabeceras Authorization, y cualquier método que tu mapa no cubra. Trata Mcp-Name como una pista que debe coincidir con el cuerpo una vez decodificada, y rechaza todo cuerpo que no puedas analizar exactamente como lo hace el servidor. Responde a un ámbito que falte con un 403 y un desafío insufficient_scope que nombre todos los ámbitos de la herramienta, y limita required_scopes a lo que necesita cada petición.
Esta parte aún no está traducida, así que está en inglés.
Ask for more scope when a call needs it
Step-up is the 403 from Scope tools by what the token allows and the client's answer to it: on insufficient_scope, the client authorizes again with the union of the scopes it asked for before and the scopes in the challenge, retries, and limits how many times it tries (authorization). The union rule is in the pinned revision's text, not in revision 2025-11-25's (2025-11-25 authorization). Without it, a client asking for refunds:write alone would lose orders:read, and its next order lookup would restart the cycle. The SDK's client steps up on 403 and unions the scopes (mcp/client/auth/oauth2.py).
A support lead and a staff member without that role each refund order O-1004 through the SDK's client. The refund, €24.98, is within the policy limit, so no confirmation is involved. The scripted consent lets the lead grant all three scopes and the other user only the two read scopes.
1"""Step-up: the SDK's client meets the refund's 403, authorizes again for the union of its scopes and `refunds:write`, and2retries. A user who may not grant `refunds:write` gets a token without it and a failed refund. The point rests on the3refund status line for the lead and the refund failure line for the other user, with the scopes each authorization asked for."""4import asyncio5import os67from lib import auth_server, loopback, oauth_client, protected_shop, shop_api8910async def refund(label: str, user_scopes: tuple[str, ...]) -> None:11 # user_scopes are the scopes this user may grant at consent; the scripted browser grants no more12 with auth_server.serve(user_scopes=user_scopes) as issuer, protected_shop.serve(issuer.url) as url:13 browser, storage = oauth_client.ScriptedBrowser(), oauth_client.MemoryStorage()14 async with oauth_client.connect(url, browser=browser, storage=storage) as client:15 quote = await client.call_tool("quote_refund", {"order_id": "O-1004", "reason": "arrived cracked"})16 print(f"{label}, quote amount:", quote.structured_content["amount"])17 print(f"{label}, quote within limit:", quote.structured_content["within_limit"])18 try:19 result = await client.call_tool("issue_refund", {"quote_id": quote.structured_content["quote_id"]})20 print(f"{label}, refund status:", result.structured_content["status"])21 except Exception as error:22 print(f"{label}, refund failed:", type(error).__name__, error)23 for number, asked in enumerate(browser.requests, start=1): # one request per authorization, in order24 print(f"{label}, authorization {number} asked for:", asked["scope"])25 print(f"{label}, token scope:", auth_server.claims(storage.tokens.access_token)["scope"])262728async def main() -> None:29 with loopback.serve(shop_api.create_app()) as api_url:30 os.environ.update(shop_api.server_env(api_url)) # the server runs in this process31 await refund("lead", auth_server.SCOPES)32 await refund("non-lead", ("orders:read", "stock:read"))333435asyncio.run(main())
python step-up-for-refunds.pylead, quote amount: 24.98
lead, quote within limit: True
lead, refund status: requested
lead, authorization 1 asked for: orders:read stock:read
lead, authorization 2 asked for: orders:read stock:read refunds:write
lead, token scope: orders:read stock:read refunds:write
non-lead, quote amount: 24.98
non-lead, quote within limit: True
non-lead, refund failed: MCPError Server returned an error response
non-lead, authorization 1 asked for: orders:read stock:read
non-lead, authorization 2 asked for: orders:read stock:read refunds:write
non-lead, token scope: orders:read stock:read
The lead's first authorization asked for orders:read stock:read, the two read scopes. The refund's 403 started a second, which asked for orders:read stock:read refunds:write, the union, although the challenge named only refunds:write. The retry went through, and the refund's status is requested.
The other user's second authorization asked for the same union. The user could grant only orders:read stock:read, and the retried call failed with MCPError Server returned an error response. The SDK stepped up once and stopped, so there was no loop. But the host got a generic error, not "this needs a lead".
Working rule: Let the SDK step up, and keep its union of scopes. List every tool a caller could gain by step-up, since a hidden tool never gets the 403 that starts it. In the host, compare the scope the token response granted with the scope the challenge asked for. When they differ, treat it as a decision, not a fault: tell the user which scope the call needs, and pass the ticket to someone who holds it. Never let an authorization server grant by step-up what a user's role doesn't allow. The client only asks, and the authorization server decides.
Lo que sale mal en producción
El servidor de la tienda, su servidor de autorización y su host funcionan todos en loopback. En producción se encuentran con servidores de autorización, pasarelas y clientes de otras personas, y cada uno de los fallos que siguen deja un rastro que puedes buscar.
Un servidor de autorización que no envía iss. Es un SHOULD en la revisión fijada, así que algunos servidores de autorización lo omiten, y el SDK entonces continúa sin ninguna defensa contra la confusión de emisor (Valida el emisor de cada respuesta). La señal es metadatos sin authorization_response_iss_parameter_supported. Revisa los metadatos de cada servidor de autorización que encuentre tu host, y mantén el host con una lista de permitidos de servidores de autorización mientras alguno de ellos omita iss.
La vuelta silenciosa al registro. Cuando un servidor de autorización no anuncia soporte para documentos de metadatos del ID de cliente, el SDK se registra dinámicamente sin advertirlo (Clientes OAuth). Busca errores de registro, o una lista creciente de clientes registrados en el servidor de autorización. Registra qué tipo de ID de cliente usó cada conexión.
La comprobación de audiencia está desactivada. Un servidor sin validate_token_resource acepta tokens emitidos para otros servidores, y la única señal es un MCPDeprecationWarning al arrancar (Vincula cada token a un solo servidor). Haz que las advertencias de AuthSettings hagan fallar el despliegue.
Un emisor con barra final. La comparación del emisor es por cadena exacta, así que https://auth.fernhill.example y https://auth.fernhill.example/ son emisores distintos, y el SDK lanza "Authorization server metadata issuer mismatch". Los modelos de metadatos del SDK conservan una URL sin ruta tal como se envió, pero un objeto AnyHttpUrl construido en Python sí le añade la barra. Pasa las URL al SDK como cadenas (Guía de migración del SDK). Verás OAuthFlowError en la primera conexión a un servidor, desde todos los hosts.
Ninguna comprobación de PKCE en el host. El cliente del SDK nunca lee code_challenge_methods_supported (Obtén un token con PKCE). Nada falla, así que la única señal es una auditoría: obtén los metadatos de cada servidor de autorización y busca S256.
Un redirect localhost secuestrado. Un documento de metadatos demuestra a qué dominio pertenece un cliente, no qué programa escucha en una URI de redirect localhost, y cualquier programa local puede enlazar el puerto primero. La especificación dice que los documentos de metadatos "no pueden prevenir por sí solos la suplantación de URL localhost", y pide a los servidores de autorización que muestren al usuario el nombre de host del redirect y que adviertan sobre URI de redirect solo localhost (consideraciones de seguridad). La pista es una pantalla de consentimiento que nombra el host real para una solicitud que nadie en esa máquina hizo.
Un servidor de autorización usado para sondear la red. Un servidor que obtiene cualquier URL de ID de cliente puede dirigirse a direcciones internas. El borrador dice que los servidores de autorización NO DEBEN obtener desde direcciones de uso especial, con una excepción de loopback solo para servidores de desarrollo que se ejecuten en loopback (borrador de documento de metadatos -02, sección 8.6). Vigila en los registros del servidor de autorización las obtenciones de metadatos a direcciones privadas.
Consentimiento cada pocos minutos. El servidor de autorización de la tienda no emite tokens de refresco, así que el host vuelve a ejecutar todo el flujo cada vez que caduca un token, y el usuario consiente de nuevo. Si emites tokens de refresco a hosts, que son clientes públicos, el servidor de autorización DEBE rotarlos, y los servidores MCP NO DEBERÍAN incluir offline_access en sus desafíos ni scopes_supported (autorización). Se manifiesta como solicitudes de autorización de un mismo host con el intervalo de la vida útil del token.
Un step-up que nunca puede tener éxito. Un servidor cuyo 403 nombra un ámbito que el servidor de autorización no conoce, o uno que el rol del usuario no puede conceder, envía cada llamada de ese tipo por una segunda autorización que falla. Pares de solicitudes de autorización para una misma llamada a herramienta, seguidos de un error genérico en el host, son la pista (Pide más ámbito cuando una llamada lo necesite).
Regla práctica: Ejecuta tres sondeos contra el despliegue antes de que el servidor de la tienda reciba tráfico. Una solicitud sin token recibe 401 con una URL de resource_metadata. Un token para otro recurso recibe 401. Un reembolso con un token de solo lectura recibe 403 con scope="refunds:write", y el mismo reembolso con una segunda cabecera Authorization recibe 400. Después revisa los metadatos de cada servidor de autorización que usen tus hosts para ver S256, soporte de iss y soporte de documentos de metadatos, y vigila los 401, los 403 y las solicitudes de autorización por host.
Decisiones que tomó este capítulo
- El servidor de la tienda es un servidor de recursos OAuth sobre Streamable HTTP, configurado con
AuthSettingsdel SDK: la URL de su endpoint comoresource_server_url,orders:readystock:readcomorequired_scopes, yvalidate_token_resource=True. - Los ejemplos usan un servidor de autorización didáctico,
lib.auth_server, y no el integrado del SDK: solo S256,resourceobligatorio,issenviado y anunciado, códigos de un solo uso, tokens de acceso JWT conaudyscope, y sin tokens de actualización. No inicia sesión de nadie, y su clave deriva de la semilla pública del libro, por lo que nunca debe desplegarse. Un despliegue usa un servidor de autorización consolidado que ofrezca solo S256, respeteresource, envíe y anuncieiss, y admita Client ID Metadata Documents. - El host de soporte se identifica mediante un Client ID Metadata Document en una URL
https://sobresupport.fernhill.example. En los ejemplos, el servidor de autorización guarda una copia local del documento en lugar de recuperarlo, y no se ofrece Dynamic Client Registration. - Los hosts usan el
OAuthClientProviderdel SDK conclient_metadata_url, y añaden la comprobación de soporte de PKCE que el SDK omite. - Los tokens se verifican por audiencia mediante
AuthSettings, y el verificador de tokens informa deaudcomoAccessToken.resource. - Los scopes son por herramienta:
orders:readpara buscar, leer y cotizar pedidos,stock:readpara el stock, yrefunds:write, que solo pueden conceder los responsables de soporte, para los reembolsos. Un middleware HTTP decide a partir del cuerpo JSON-RPC analizado, conMcp-Nameúnicamente como pista que debe coincidir con él, y con el único token que autentica el SDK, rechazando una segunda cabeceraAuthorization. Responde a un scope ausente con un desafío 403, y rechaza las herramientas y los métodos con nombre que no tiene asignados. refunds:writese obtiene mediante step-up, nunca por defecto. No aparece enscopes_supported, y el cliente del SDK pide la unión de scopes cuando un reembolso lo necesita.- Todas las herramientas permanecen en
tools/list, para que el step-up pueda iniciarse. Ocultar herramientas según el scope está disponible enlib.tool_scopespero no se usa. - La persona en cuyo nombre actúa el host se obtiene del
subdel token verificado, medianteget_access_token(), y nunca de un argumento de la herramienta: en el host de soporte, un miembro del personal. El cliente al que se refiere un ticket se obtiene del registro del ticket, que el servidor busca y comprueba, y no del token ni de un argumento. Cuando los clientes inician sesión por sí mismos, consulta Evita que el servidor actúe como confused deputy.
Este capítulo, en esta edición
Edición 2026.11.14Ejemplos verificados el 19 de nov de 2026Superan la prueba 7 de 7 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.14.