Autorize clientes com OAuth
Cerca de 43 minutos min de leitura, com 7 exemplos em 9 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.14. Leia o original
Nesta página
- Encontre o servidor de autorização a partir do recurso
- Identify the client with a metadata document
- Obter um token com PKCE
- Vincule cada token a um servidor
- Valide o emissor de cada resposta
- Defina escopos para as ferramentas conforme o que o token permite
- Ask for more scope when a call needs it
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você será capaz de proteger o servidor Model Context Protocol da loja com OAuth. Você publica os metadados que levam um cliente ao servidor de autorização, identifica o host da equipe de suporte com um Client ID Metadata Document, obtém tokens com PKCE, aceita apenas tokens emitidos para o servidor da loja, detecta um ataque de mix-up pelo issuer de cada resposta, e exige um escopo por ferramenta, com step-up quando um reembolso precisar de mais. As afirmações deste capítulo são as da especificação na revisão 2026-07-28, tal como o mcp 2.3.0, o SDK Python, a implementa.
Servir sobre Streamable HTTP transferiu shop-support, o servidor pelo qual a equipe de suporte da loja consulta pedidos e emite reembolsos, para um endereço HTTP, de modo que os hosts dela pudessem compartilhá-lo. Sua verificação de Origin barra páginas da web e nada mais: qualquer programa que alcance a porta pode consultar pedidos e emitir reembolsos (Rejeite requisições de outras origens). Por isso, a loja precisa saber qual host está chamando, em nome de qual pessoa e o que essa pessoa pode fazer. A equipe de suporte pode consultar pedidos e estoque; somente um líder de suporte pode emitir reembolsos.
O Model Context Protocol (MCP) responde com OAuth 2.1. A autorização é opcional no MCP e pertence aos transportes HTTP: um servidor stdio obtém suas credenciais do ambiente (autorização). Um servidor MCP protegido é um servidor de recursos OAuth, o cliente do host para ele é um cliente OAuth, e um servidor de autorização emite os tokens, seja junto ao servidor MCP, seja separado dele. Você conhece esse fluxo do lado do cliente de outras APIs. O que o MCP muda é que um cliente não sabe nada sobre um servidor de antemão. Ele parte de uma URL; por isso, a descoberta, a identidade do cliente e o público do token precisam funcionar sem nenhuma configuração prévia entre os dois.
Quatro módulos compartilhados em examples/lib/ trazem a configuração deste capítulo, para que cada exemplo mostre apenas a sua ideia:
lib.auth_serveré o servidor de autorização da loja, em loopback: metadados, o grant de código de autorização com PKCE,issem todas as respostas, e tokens de acesso JWT vinculados a um único servidor. O consentimento é roteirizado, substituindo a pessoa no navegador. Trata-se de um servidor didático para estes exemplos em loopback, e você nunca deve implantá-lo. Ele não autentica ninguém, e sua chave de assinatura deriva da semente pública do livro, de modo que qualquer pessoa com o livro pode gerar tokens que ele aceita. Uma implantação usa um servidor de autorização consolidado que atenda às verificações deste capítulo. O SDK Python tem um servidor de autorização próprio, mas sua documentação desaconselha o uso em servidores novos, e seus metadados não anunciamissnem Client ID Metadata Documents (documentação de autorização do SDK).lib.oauth_clienté o lado do host: oOAuthClientProviderdo SDK com armazenamento de tokens em memória, e um navegador roteirizado que segue os redirecionamentos do servidor de autorização e devolve a resposta ao SDK.lib.tool_scopesacrescenta a verificação de escopo por ferramenta que o SDK não tem.lib.protected_shopreúne tudo: as cinco ferramentas do capítulo 3 protegidas por OAuth, como este capítulo as deixa.
Tudo roda em 127.0.0.1 sobre HTTP simples. Isso é aceitável apenas para desenvolvimento local. Em produção, todo endpoint do servidor de autorização DEVE ser servido sobre HTTPS (considerações de segurança).
Encontre o servidor de autorização a partir do recurso
Um cliente que tem apenas a URL de um servidor precisa descobrir, com o próprio servidor, onde obter um token, e a revisão fixada faz isso em duas etapas. Primeiro, servidores MCP DEVEM publicar Protected Resource Metadata (RFC 9728), um documento JSON que nomeia o recurso e lista pelo menos um servidor de autorização (authorization). Uma requisição sem token recebe 401, e seu cabeçalho WWW-Authenticate aponta para esse documento em um parâmetro resource_metadata. Um cliente que não encontra esse parâmetro tenta a URI well-known, /.well-known/oauth-protected-resource com o caminho do servidor inserido, e depois sem o caminho (authorization server discovery). Em segundo lugar, o cliente busca os metadados do próprio servidor de autorização (RFC 8414), que listam seus endpoints e o que ele suporta.
Dois valores devem coincidir ao longo do caminho. O resource nos metadados do servidor deve ser idêntico à URL que o cliente usou, ou o cliente não deve usar os metadados (RFC 9728, seção 3.3). E o issuer nos metadados do servidor de autorização deve ser idêntico ao issuer a partir do qual o cliente construiu a URL well-known (RFC 8414, seção 3.3). Ambas as verificações impedem que um cliente confie em um documento que descreve outro servidor.
O servidor da loja informa sua própria URL, e o servidor de autorização informa seu issuer. O SDK faz a parte do servidor quando você fornece um MCPServer com um AuthSettings e um verificador de token: issuer_url nomeia o servidor de autorização, resource_server_url é a URL do próprio endpoint do servidor, e required_scopes lista os escopos que toda requisição exige. O servidor da loja exige orders:read e stock:read, porque todo chamado precisa de um ou de ambos. refunds:write vem depois, e somente quando um reembolso precisar dele. O verificador de token é lib.auth_server.JwtVerifier, que verifica a assinatura, o issuer e a expiração de um token. Em loopback, a porta, e portanto a URL do recurso, só são conhecidas depois que o socket é aberto. Por isso o servidor é construído em uma função de sua URL base, e serve_built de lib.auth_server abre o socket primeiro. Em seguida, o exemplo faz o papel de cliente: envia tools/list sem token e segue a resposta.
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']
A primeira requisição recebeu 401, com um desafio contendo error, error_description, resource_metadata e o erro invalid_token. Esse erro é uma escolha do SDK, e um desvio da RFC 6750, que diz que um servidor NÃO DEVERIA incluir um código de erro quando uma requisição não traz credencial alguma (RFC 6750, seção 3.1).
O caminho da URL de metadados é /.well-known/oauth-protected-resource/mcp, o prefixo well-known com o caminho do servidor inserido, como pede a RFC 9728. Os metadados nomeiam a URL do próprio endpoint como seu recurso, listam 1 servidor de autorização, e informam scopes_supported como orders:read stock:read, que o SDK preenche a partir de required_scopes.
O desafio não tem parâmetro scope, porque o 401 do SDK nunca envia um (mcp/server/auth/middleware/bearer_auth.py). Por isso um cliente recorre a scopes_supported. A ordem da especificação é primeiro o parâmetro scope do desafio, depois todos os escopos em scopes_supported, e por fim nenhum scope (authorization). É por isso que scopes_supported deve ser o menor conjunto que funciona, e não todos os escopos que o servidor conhece: seja o que for que liste, todo host solicita a cada usuário.
Os metadados do servidor de autorização informam como issuer a URL de onde o cliente os buscou, e declaram três coisas em que o restante do capítulo se apoia: métodos PKCE ['S256'], suporte a Client ID Metadata Documents, e iss nas respostas de autorização. O cliente do SDK faz as duas verificações correspondentes para você. Ele lança OAuthFlowError quando o issuer dos metadados difere do esperado, comparado como strings simples (guia de migração do SDK). Sua verificação de recurso é mais flexível que a RFC 9728: aceita metadados cujo resource é um prefixo de caminho da mesma origem da URL do servidor (mcp/shared/auth_utils.py). Um callback validate_resource_url em OAuthClientProvider substitui essa verificação pela sua.
Regra prática: Dê a cada servidor protegido um AuthSettings com a URL do seu endpoint como resource_server_url, exatamente como os clientes a digitarão, e o menor required_scopes que toda requisição exige. Verifique a cadeia com uma requisição que não traz token: um 401, uma URL resource_metadata, metadados cujo resource é o endpoint, e metadados do servidor de autorização cujo issuer é a URL de onde você os buscou. Quando um valor difere por uma barra final ou uma porta, corrija a configuração em vez de flexibilizar o cliente.
Esta parte ainda não foi traduzida, por isso está em 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.
Obter um token com PKCE
Com o seu client ID obtido em Identifique o cliente com um documento de metadados, o host pode solicitar um token. O MCP usa a concessão de código de autorização (authorization code grant). O host envia o navegador do usuário ao endpoint de autorização do servidor de autorização; o usuário entra na conta e concede consentimento; e o navegador retorna ao redirect URI do host com um código. Em seguida, o host troca esse código por um token no endpoint de token. Três parâmetros dessa troca concentram a maior parte da sua segurança.
O PKCE vincula o código ao cliente que o solicitou. O cliente gera um code_verifier aleatório, envia o hash SHA-256 dele como code_challenge junto com code_challenge_method=S256, e revela o verificador somente na requisição de token; assim, quem interceptar o código não o possui. Clientes MCP DEVEM usar PKCE com S256 e DEVEM recusar-se a prosseguir se os metadados do servidor de autorização não tiverem code_challenge_methods_supported (considerações de segurança). Desde o draft-16, o OAuth 2.1 proíbe explicitamente o método plain, em que o desafio é o próprio verificador (OAuth 2.1 draft-16, seção 7.5.2). A especificação do MCP cita o draft-13, que ainda o permitia (OAuth 2.1 draft-13).
O parâmetro resource (RFC 8707) indica, pela URI canônica do servidor, para qual servidor o token se destina. Clientes MCP DEVEM enviá-lo tanto na requisição de autorização quanto na requisição de token, tenha ou não o servidor de autorização suporte a ele (autorização). E state, que o cliente verifica quando o navegador retorna, vincula a resposta à requisição.
O cliente do SDK executa esse fluxo inteiro para o host, e o exemplo o acompanha do lado do servidor de autorização. lib.oauth_client.connect entrega ao cliente um OAuthClientProvider com a URL do documento de metadados do host e um navegador roteirizado no lugar de uma pessoa. O navegador abre a URL de autorização, segue os redirecionamentos e para no primeiro endereçado ao redirect URI. O consentimento da pessoa no servidor de autorização também é roteirizado: o usuário autenticado concede todos os escopos solicitados que o seu papel permite. O exemplo chama get_order_status, lê o que o servidor de autorização registrou e, em seguida, envia ao servidor de autorização três requisições que o SDK jamais enviaria.
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
A chamada funcionou, e o pedido O-1873 está delivered. A requisição de autorização trouxe response_type, client_id, redirect_uri, state, code_challenge, code_challenge_method, resource, scope, com o método S256, e o seu desafio é o hash do verificador que a requisição de token revelou. Ambas as requisições indicaram o mesmo resource, a URL do endpoint. O token de acesso é um JWT cujo aud é a URL do servidor e cujo iss é o servidor de autorização. Seu escopo é orders:read stock:read, o scopes_supported do servidor, porque o 401 não nomeou nenhum escopo.
O sub do token, staff-0007, nomeia o integrante da equipe de suporte em nome de quem o host atua, e não um cliente; o servidor o lê de get_access_token().subject do SDK. Assim, um token de integrante da equipe não pode, por si só, substituir SHOP_CUSTOMER_ID, que a conclusão de pedido em Complete os argumentos para o usuário lia do seu ambiente por stdio. Em um host de suporte, o cliente vem do registro do chamado em que a integrante da equipe está trabalhando, que o servidor consulta e verifica, e nunca de um argumento de ferramenta. Somente quando os clientes se autenticam no próprio host é que sub identifica o cliente, caso tratado em Impeça que o servidor atue como um deputado confuso. Não há refresh token (None): o servidor de autorização da loja não emite nenhum, e a especificação orienta os clientes a não presumir um (autorização).
As três requisições que o SDK nunca envia mostram o que o PKCE e os códigos de uso único impedem. O mesmo código enviado uma segunda vez recebeu 400 invalid_grant, porque um código funciona uma única vez. Um código novo enviado com um verificador adivinhado recebeu invalid_grant; logo, um código roubado isoladamente não tem valor algum. Uma requisição com plain recebeu "invalid_request / PKCE with S256 is required", porque o servidor de autorização da loja aceita apenas S256.
Uma verificação fica a cargo do host. O cliente do SDK sempre envia S256, mas nunca lê code_challenge_methods_supported; por isso, prossegue com um servidor de autorização cujos metadados omitem esse campo (mcp/client/auth/oauth2.py). Um host que precise cumprir a especificação busca os metadados de cada servidor de autorização por conta própria antes de se conectar, e recusa qualquer servidor que não liste S256.
Regra prática: Deixe que o OAuthClientProvider do SDK execute o fluxo de código de autorização, e verifique uma vez, do lado do servidor de autorização, o que ele envia: S256, state e um resource igual à URL do servidor em ambas as requisições. Acrescente a verificação que o SDK ignora e recuse um servidor de autorização cujos metadados não listem S256. Em um servidor de autorização que você opera, aceite apenas S256, torne os códigos de uso único e de curta duração, e vincule cada código ao seu cliente, ao seu redirect URI e ao seu resource.
Vincule cada token a um servidor
O token obtido em Obtenha um token com PKCE nomeia o servidor da loja em aud, porque o host enviou resource. Isso não protege ninguém, a menos que o servidor verifique esse valor. Um access token é uma credencial de portador, de modo que quem o possuir pode apresentá-lo. Suponha que o host de suporte também se conecte a um servidor MCP de um parceiro que confia no mesmo servidor de autorização. O servidor do parceiro recebe os tokens que o host obtém para ele. Se o servidor da loja aceitasse esses tokens, o operador do parceiro poderia reutilizá-los na loja. A RFC 8707 diz que o servidor de autorização DEVE restringir o público de cada token ao recurso solicitado, de modo que um token "apresentado legitimamente a um recurso não possa então ser usado por esse recurso e apresentado em outro lugar" (RFC 8707). A outra metade cabe ao servidor: servidores MCP DEVEM validar que um token foi emitido tendo-os como público (audience), e NÃO DEVEM aceitar nem repassar qualquer outro token (autorização).
No SDK Python de mcp 2.3.0, a metade do servidor vem desativada por padrão. AuthSettings.validate_token_resource decide se o servidor recusa um token cujo AccessToken.resource não seja resource_server_url. Quando não definido, ele emite um aviso com MCPDeprecationWarning e se comporta como False, e a versão 3.0 torna True o padrão (mcp/server/auth/settings.py). O SDK compara os dois valores como URLs. A diferença de maiúsculas e minúsculas no esquema e no host, uma porta padrão ou uma barra final não fazem diferença (mcp/server/auth/middleware/bearer_auth.py), e a comparação usa o que o seu verificador de token colocar em AccessToken.resource. A outra forma é um verificador que confere aud por conta própria.
Dois tokens mostram qual verificação faz o trabalho. O exemplo assina os dois com a chave do servidor de autorização da loja, um para o servidor da loja e outro para o do parceiro, https://partner.example/mcp, e os apresenta ao servidor da loja em três configurações: o padrão do SDK, validate_token_resource=True, e um verificador que passa a URL da loja para a biblioteca JWT como público esperado.
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
Com o padrão do SDK, o token do parceiro obteve 200, e o servidor listou suas ferramentas para um token emitido para outra pessoa. O único sinal foi um aviso na inicialização, MCPDeprecationWarning. Qualquer uma das duas verificações recusa o token do parceiro. Com validate_token_resource=True, ele obteve 401, e com a verificação de público no verificador obteve 401. Ambas as recusas são 401 com invalid_token, a resposta que a especificação prevê para um token que não é válido para o servidor. O token da própria loja foi aceito nas três configurações, e nenhuma das correções emitiu aviso.
Recomendamos validate_token_resource=True, que lib.protected_shop define. Ele declara a decisão ao lado das outras configurações de autorização do servidor e sobrevive a uma troca de verificador de token. Verifique aud também no verificador quando ele já decodificar o token, pois a segunda verificação não custa nada.
Regra prática: Defina validate_token_resource=True em todo servidor protegido, e faça o verificador de token preencher AccessToken.resource a partir do aud do token. Trate um MCPDeprecationWarning vindo de AuthSettings como uma implantação com falha, e não como ruído. Teste a verificação com um token para outro recurso do mesmo servidor de autorização, que deve receber 401. Um servidor que chama outro serviço em nome de um cliente obtém o seu próprio token para esse serviço e nunca repassa o token do cliente (Nunca repasse o token de um cliente).
Valide o emissor de cada resposta
Vincular o público-alvo, como faz Vincule cada token a um servidor, impede que um token funcione no servidor errado. Um ataque de mix-up ocorre antes, no código de autorização. Um host que se comunica com vários servidores de autorização envia cada código ao servidor que ele acredita ter respondido. No mix-up, o servidor de autorização do atacante faz o host iniciar um fluxo com ele e, em seguida, encaminha o navegador do usuário para um servidor de autorização honesto. O código do servidor honesto chega ao URI de redirecionamento do host. O host, ainda acreditando que está falando com o atacante, envia o código ao endpoint de token do atacante. Somente o PKCE não impede isso, "pois o cliente transmite o code_verifier ao endpoint de token do atacante" (melhores práticas de segurança). Tampouco impede o resource, que o atacante reescreve na requisição que encaminha.
A defesa é o parâmetro iss da RFC 9207. O servidor de autorização se identifica no redirecionamento, e o cliente compara esse nome com o servidor para o qual enviou o usuário. A revisão fixada introduziu essa verificação (changelog). Antes de redirecionar, o cliente registra o emissor a partir dos metadados validados do servidor de autorização e compara iss com esse registro por comparação exata de cadeias de caracteres, sem normalização de maiúsculas, portas ou barras (autorização).
As regras são condicionais. Os servidores de autorização DEVERIAM incluir iss, e aquele que o fizer DEVE anunciar authorization_response_iss_parameter_supported. Um cliente DEVE comparar um iss que esteja presente, independentemente do que os metadados informem, e DEVE rejeitar uma resposta sem iss somente quando o servidor tiver anunciado suporte. Caso contrário, ele prossegue. Em caso de divergência, o cliente não deve agir com base em nenhum error presente na resposta, nem exibi-lo. A especificação prevê que uma revisão posterior torne iss um DEVE para os servidores de autorização (autorização). Comparar um iss presente que não foi anunciado usa a margem que a RFC 9207 deixa à política local, e o padrão é que os clientes DEVERIAM descartar essa resposta (RFC 9207, seção 2.4).
No caso da loja, o atacante é o parceiro, e o MixUp, de lib.auth_server, faz esse papel. O servidor MCP do parceiro indica o servidor de autorização do atacante, que copia os metadados do servidor de autorização da loja sem suporte a iss. Seu endpoint de autorização encaminha o navegador ao servidor de autorização da loja, levando a própria requisição do host reescrita para pedir o servidor da loja e todos os escopos. O ID de cliente do host é o URL de um documento de metadados, que funciona com qualquer servidor de autorização, de modo que o servidor de autorização da loja vê uma requisição vinda do host de suporte real.
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
O ataque é executado duas vezes, contra um servidor de autorização da loja que envia iss e contra outro que não envia, e cada execução exibe o que o host viu e o que o atacante obteve. Nas duas execuções, o usuário deu consentimento no servidor de autorização da loja, porque a requisição diante dele vinha do host de suporte real. Quando a loja envia iss, a resposta trazia o emissor shop's, o SDK parou com OAuthFlowError Authorization response iss mismatch, e o atacante recebeu 0 códigos.
Quando a loja omite iss, a resposta trazia none, e o SDK prosseguiu, como a especificação diz que deve fazer para um servidor que nunca anunciou iss. O atacante recebeu 1 código com o seu verificador, resgatou-o no servidor de autorização da loja e agora possui um token para o servidor da loja com o escopo orders:read stock:read refunds:write, incluídos os reembolsos. O host viu apenas OAuthTokenError Token exchange failed (400).
Portanto, a verificação protege um host somente quando o servidor honesto envia iss. As melhores práticas de segurança afirmam que a verificação não oferece proteção contra um servidor honesto que omite iss (melhores práticas de segurança). O SDK segue exatamente a tabela da especificação (validate_authorization_response_iss em mcp/client/auth/utils.py). Portanto, a possibilidade de os tokens da loja serem roubados dessa forma depende do servidor de autorização da loja, e não do host. A outra defesa descrita pela RFC 9700, um URI de redirecionamento distinto para cada servidor de autorização, não ajuda este host. A RFC 9700 afirma que ela "não pode ser usada em cenários em que os clientes se registram apenas uma vez para o uso de vários emissores diferentes", e que ela deve ser usada somente quando nada mais estiver disponível (RFC 9700, seção 4.4.2.2). Um cliente identificado por um documento de metadados se enquadra nesse caso, com um único client_id e uma única lista de URIs de redirecionamento para todos os servidores de autorização; assim, o servidor honesto aceita qualquer URI listado que o atacante encaminhe. O que um host pode fazer sem a ajuda do servidor é limitar quais servidores de autorização ele usa. Um servidor do atacante que não esteja na lista de permissões do host nunca inicia um fluxo.
Regra prática: Envie iss em todo servidor de autorização que você executar e anuncie-o com authorization_response_iss_parameter_supported: true, para que os clientes rejeitem uma resposta sem ele. Em um host, mantenha a verificação do SDK, não acrescente normalização em torno dela e trate qualquer divergência como um ataque: não mostre ao usuário nenhum texto de erro daquela resposta. Quando um host precisar usar um servidor de autorização que não envia iss, restrinja o host a uma lista de permissões de servidores de autorização e recuse ou avise o usuário sobre qualquer servidor que não esteja nela. Não conte com um URI de redirecionamento separado por servidor quando o host for identificado por um documento de metadados.
Defina escopos para as ferramentas conforme o que o token permite
Com as verificações em Vincule cada token a um único servidor e Valide o emissor de cada resposta concluídas, o servidor da loja sabe quem está chamando. Ainda assim, ele precisa decidir o que cada chamador pode fazer. O token lista os escopos concedidos, e a loja tem três: orders:read para localizar, ler e cotar pedidos, stock:read para consultar o estoque e refunds:write para emitir um reembolso, que apenas os líderes de suporte podem conceder.
O SDK verifica os escopos por endpoint, e não por ferramenta. AuthSettings.required_scopes se aplica a toda requisição, e o próprio 403 do SDK não nomeia nenhum scope (mcp/server/auth/middleware/bearer_auth.py). A especificação pede um desafio que o cliente possa usar: um 403 com WWW-Authenticate: Bearer error="insufficient_scope", os scope que a operação exige e resource_metadata, com “todos os escopos exigidos para a operação atual em um único desafio” (authorization). Um middleware HTTP pode enviar isso. Na revisão fixada, cada tools/call nomeia sua ferramenta no cabeçalho Mcp-Name, mas os servidores DEVEM decodificar sua forma =?base64?...?= antes de compará-la com o corpo (Streamable HTTP). Uma verificação do cabeçalho bruto deixa passar um issue_refund codificado. E um cliente na revisão 2025-11-25, que o servidor do SDK ainda aceita no mesmo endpoint, não envia nenhum Mcp-Name.
Portanto, lib.tool_scopes.require decide sobre o que o servidor vai executar, com a credencial que o SDK usa. Ele lê a ferramenta a partir de params.name do corpo analisado, e o cabeçalho Mcp-Name, decodificado da forma como o SDK o decodifica, deve corresponder a esse nome; caso contrário, a requisição recebe -32020, HeaderMismatch. Um corpo que não seja um único objeto JSON, ou que repita uma chave, é recusado. O SDK autentica com o primeiro cabeçalho Authorization (mcp/server/auth/middleware/bearer_auth.py), por isso o middleware recusa dois deles com 400 invalid_request, e lê o token por meio de BearerAuthBackend do SDK, respondendo 401 a uma chamada de ferramenta cujo token não pode ser verificado.
O middleware nega por padrão: uma ferramenta ausente do mapa é recusada. Métodos que não nomeiam nada, como tools/list, precisam apenas dos escopos do endpoint, e qualquer outro método, como prompts/get, resources/read ou tasks/get, recebe 403. lib.protected_shop mapeia as cinco ferramentas, e lib.tool_scopes.hide_unscoped pode ocultar as ferramentas que um token não pode chamar (Mantenha a lista de ferramentas pequena). Com os dois escopos de leitura, o exemplo lista as ferramentas com a ocultação desligada e ligada, e depois envia chamadas escritas à mão.
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
O servidor obtém o escopo da ferramenta no corpo. get_order_status recebeu 200, e issue_refund recebeu 403, com o desafio Bearer error="insufficient_scope", scope="refunds:write". Esse desafio nomeia refunds:write e traz uma URL de resource_metadata.
Com a ocultação desligada, o token vê find_orders, get_order_status, quote_refund, issue_refund, check_stock; com ela ligada, find_orders, get_order_status, quote_refund, check_stock. Em ambos os casos, o escopo de cache da lista é private. Esse é o padrão do SDK, que se adequa a uma lista que depende do token (Armazene em cache os resultados da lista).
Um reembolso cujo Mcp-Name declarava get_order_status recebeu 400 -32020. Duas requests que uma verificação apenas do cabeçalho deixaria passar foram recusadas por escopo. O reembolso com Mcp-Name em Base64 recebeu 403, e o reembolso de um cliente em 2025-11-25 recebeu 403.
Um reembolso com o token somente leitura e um segundo cabeçalho Authorization sem sentido recebeu 400 invalid_request. Uma verificação que lesse o último cabeçalho teria permitido que o SDK emitisse o reembolso com o token somente leitura. Um prompts/get não mapeado recebeu 403. Com refunds:write, a chamada chegou à ferramenta, que respondeu 200 True: primeiro o status e depois o isError do resultado, true, porque o ID de cotação do exemplo não existe.
Regra prática: Mapeie cada ferramenta para os seus escopos e autorize a requisição analisada com exatamente a credencial que o SDK autentica, nunca apenas com base em um cabeçalho. Recuse dois cabeçalhos Authorization, e qualquer método que o seu mapa não cubra. Trate Mcp-Name como uma dica que deve corresponder ao corpo depois de decodificado, e recuse qualquer corpo que você não consiga analisar exatamente como o servidor o faz. Responda a um escopo ausente com um desafio 403 insufficient_scope que nomeie todos os escopos da ferramenta, e mantenha required_scopes restrito ao que toda requisição precisa.
Esta parte ainda não foi traduzida, por isso está em 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.
O que dá errado em produção
O servidor da loja, o seu servidor de autorização e o seu host funcionam todos em loopback. Em produção, eles encontram servidores de autorização, gateways e clientes de outras pessoas, e cada uma das falhas a seguir deixa um rastro que você pode procurar.
Um servidor de autorização que não envia iss. Trata-se de um SHOULD na revisão fixada, então alguns servidores de autorização o omitem, e o SDK então prossegue sem nenhuma defesa contra mix-up (Valide o emissor de cada resposta). O sinal é um metadado sem authorization_response_iss_parameter_supported. Verifique os metadados de cada servidor de autorização que o seu host encontra, e mantenha o host restrito a uma lista de permissões de servidores de autorização enquanto algum deles omitir iss.
O fallback silencioso para o registro. Quando um servidor de autorização não anuncia suporte a Client ID Metadata Document, o SDK se registra dinamicamente sem avisar (Clientes OAuth). Procure erros de registro, ou uma lista crescente de clientes registrados no servidor de autorização. Registre qual tipo de client ID cada conexão usou.
A verificação de audiência está desligada. Um servidor sem validate_token_resource aceita tokens emitidos para outros servidores, e o único sinal é um MCPDeprecationWarning na inicialização (Vincule cada token a um servidor). Faça com que avisos de AuthSettings façam a implantação falhar.
Um emissor com barra final. A comparação do emissor é feita por string exata, então https://auth.fernhill.example e https://auth.fernhill.example/ são emissores diferentes, e o SDK levanta "Authorization server metadata issuer mismatch". Os modelos de metadados do SDK mantêm uma URL sem caminho como foi enviada, mas um objeto AnyHttpUrl construído em Python ainda ganha a barra. Passe URLs para o SDK como strings (guia de migração do SDK). Você verá OAuthFlowError na primeira conexão com um servidor, a partir de todos os hosts.
Nenhuma verificação de PKCE no host. O cliente do SDK nunca lê code_challenge_methods_supported (Obtenha um token com PKCE). Nada falha, então o único sinal é uma auditoria: busque os metadados de cada servidor de autorização e procure por S256.
Um redirecionamento localhost tomado por outro. Um documento de metadados comprova a qual domínio um cliente pertence, não qual programa escuta em um URI de redirecionamento localhost, e qualquer programa local pode associar a porta primeiro. A especificação diz que documentos de metadados "não podem, por si sós, impedir a falsificação de URL localhost", e pede que servidores de autorização mostrem o nome do host do redirecionamento ao usuário e avisem sobre URIs de redirecionamento somente localhost (considerações de segurança). O indício é uma tela de consentimento que nomeia o host real para uma requisição que ninguém naquela máquina fez.
Um servidor de autorização usado para sondar a rede. Um servidor que busca qualquer URL de client ID pode ser direcionado a endereços internos. O rascunho diz que servidores de autorização NÃO DEVEM buscar em endereços de uso especial, com uma exceção de loopback apenas para servidores de desenvolvimento que rodam em loopback (documento de metadados rascunho -02, seção 8.6). Observe buscas de metadados para endereços privados nos logs do servidor de autorização.
Consentimento a cada poucos minutos. O servidor de autorização da loja não emite refresh token, então o host executa o fluxo inteiro outra vez sempre que um token expira, e o usuário consente novamente. Se você emite refresh tokens para hosts, que são clientes públicos, o servidor de autorização DEVE rotacioná-los, e servidores MCP NÃO DEVERIAM listar offline_access em seus desafios nem em scopes_supported (autorização). Isso aparece como requisições de autorização de um mesmo host no intervalo da duração do token.
Um step-up que nunca pode dar certo. Um servidor cujo 403 nomeia um escopo que o servidor de autorização não conhece, ou que o papel do usuário não pode conceder, envia cada chamada desse tipo por uma segunda autorização que falha. Pares de requisições de autorização para uma mesma chamada de ferramenta, seguidos de um erro genérico no host, são o sinal (Peça mais escopo quando uma chamada precisar).
Regra prática: Execute três sondagens na implantação antes de o servidor da loja receber tráfego. Uma requisição sem token recebe 401 com uma URL resource_metadata. Um token para outro recurso recebe 401. Um reembolso com um token somente leitura recebe 403 com scope="refunds:write", e o mesmo reembolso com um segundo cabeçalho Authorization recebe 400. Depois, verifique os metadados de cada servidor de autorização que seus hosts usam quanto a S256, suporte a iss e suporte a documento de metadados, e acompanhe os 401s, 403s e requisições de autorização por host.
Decisões tomadas neste capítulo
- O servidor da loja é um servidor de recursos OAuth sobre Streamable HTTP, configurado com o
AuthSettingsdo SDK: a URL do seu endpoint comoresource_server_url,orders:readestock:readcomorequired_scopes, evalidate_token_resource=True. - Os exemplos usam um servidor de autorização didático,
lib.auth_server, e não o servidor integrado do SDK: apenas S256,resourceobrigatório,issenviado e anunciado, códigos de uso único, tokens de acesso JWT comaudescope, e sem tokens de atualização. Ele não faz login de ninguém, e sua chave deriva da semente pública do livro, por isso nunca deve ser implantado. Uma implantação usa um servidor de autorização consolidado que oferece apenas S256, respeitaresource, envia e anunciaisse oferece suporte a Client ID Metadata Documents. - O host de suporte é identificado por um Client ID Metadata Document em uma URL que começa com
https://no domíniosupport.fernhill.example. Nos exemplos, o servidor de autorização mantém uma cópia local do documento, em vez de buscá-lo, e o Dynamic Client Registration não é oferecido. - Os hosts usam o
OAuthClientProviderdo SDK comclient_metadata_url, e acrescentam a verificação de suporte a PKCE que o SDK omite. - Os tokens são verificados quanto ao público-alvo (audience) por
AuthSettings, e o verificador de tokens informaaudcomoAccessToken.resource. - Os escopos são definidos por ferramenta:
orders:readpara localizar, ler e cotar pedidos,stock:readpara estoque, erefunds:write, que só líderes de suporte podem conceder, para reembolsos. Um middleware HTTP decide com base no corpo JSON-RPC analisado, comMcp-Nameapenas como dica que precisa coincidir com ele, e com o único token que o SDK autentica, recusando um segundo cabeçalhoAuthorization. Ele responde a um escopo ausente com um desafio 403, e recusa ferramentas e métodos nomeados que não mapeia. refunds:writeé concedido por step-up, nunca por padrão. Ele não está emscopes_supported, e o cliente do SDK solicita a união dos escopos quando um reembolso o exige.- Todas as ferramentas permanecem em
tools/list, para que o step-up possa começar. Ocultar ferramentas por escopo está disponível emlib.tool_scopes, mas não é usado. - Em nome de quem o host atua vem do
subdo token verificado, por meio deget_access_token(), e nunca de um argumento da ferramenta: no host de suporte, um integrante da equipe. O cliente ao qual um chamado se refere vem do registro do chamado, que o servidor consulta e verifica, e não do token nem de um argumento. Onde os próprios clientes se autenticam, veja Impeça que o servidor atue como confused deputy.
Este capítulo, nesta edição
Edição 2026.11.14Exemplos aprovados em 19 de nov de 20267 de 7 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.14.