Por que PKCE para MCP quando os agentes não são navegadores?

PKCE (Proof Key for Code Exchange) vincula o código de autorização a um segredo criptográfico único que apenas o cliente inicial conhece. No contexto do MCP, o invasor não é uma extensão maliciosa do navegador; é um agente desonesto ou um código de autorização roubado flutuando em um log de terminal. PKCE significa que um código interceptado não pode ser resgatado sem o verificador de código original. OAuth 2.1 requer PKCE para cada fluxo de código de autorização, incluindo clientes confidenciais, portanto o MCP apenas segue as especificações.

O que é um documento de metadados de recursos protegidos?

Um documento PRM é um arquivo JSON servido em /.well-known/oauth-protected-resource que informa aos clientes OAuth onde reside o servidor de autorização, quais escopos o recurso aceita e qual identificador de recurso colocar na declaração aud. A especificação de autorização MCP adicionou PRM para que um cliente MCP descubra sua configuração de autenticação sem configuração fora de banda. O cliente busca o PRM, segue a URLauthorization_servers até os metadados AS, executa a dança OAuth e chega ao seu servidor MCP com um token de portador válido.

Preciso de registro dinâmico de cliente?

Para servidores MCP públicos expostos a muitos clientes, sim. O registro dinâmico de cliente (RFC 7591) permite que um cliente MCP se registre automaticamente em seu servidor de autorização, receba um client_id e inicie o fluxo OAuth em uma viagem de ida e volta. Sem ele, cada usuário precisa criar manualmente um aplicativo em seu painel antes de poder conectar Claude ou Cursor. Para integrações internas ou na lista de permissões, um client_id pré-provisionado ainda funciona.

Onde fica o token ao portador durante a sessão?

No cabeçalho de autorização de cada solicitação MCP. O HTTP streamable torna isso limpo; cada solicitação carrega o token e seu servidor o verifica no middleware antes de despachar a chamada da ferramenta. Tokens de acesso de curta duração (5 a 60 minutos) com tokens de atualização mantidos pelo cliente minimizam o raio de explosão de uma linha de log vazada. Nunca incorpore o token na URL; logs e proxies capturam URLs rotineiramente.

Como os escopos da ferramenta MCP se comparam aos escopos do OAuth?

O MCP se baseia na autorização baseada em função: um token carrega escopos como ferramentas:read, ferramentas:invoke:safe ou ferramentas:invoke:destructive, e anotações de ferramentas individuais declaram quais escopos são necessários. Os escopos são mapeados individualmente para escopos OAuth, para que você possa usar o mesmo design de escopo que já possui para uma API REST. A nova peça são anotações em nível de ferramenta no lado do MCP; eles tornam a decisão de autorização visível no registro da ferramenta, não apenas no código do manipulador.

Tutorial

MCP OAuth 2.1 com PKCE: proteja seu servidor agente em 7 etapas

15 de abr. de 2026 | 9 min read

A especificação MCP 2026-03-15 torna o OAuth 2.1 + PKCE o padrão de autorização para servidores de agente. Sete etapas para envio: metadados PRM, registro dinâmico de cliente, design de escopo e validação de token com código.

Padlock representing OAuth 2.1 authorization for MCP servers — Photo by FLY:D on Unsplash

A especificação MCP 2026-03-15 bloqueia OAuth 2.1 com PKCE como o padrão de autorização para servidores MCP remotos. As chaves de API nas variáveis de ambiente ainda funcionam no primeiro dia, mas o registro, Claude Desktop, Cursor, VS Code Copilot e Windsurf preferem servidores apoiados por OAuth quando os usuários procure integrações. Se o seu servidor ainda solicitar um portador de longa duração em um arquivo de configuração, você estão deixando um pedaço da distribuição sobre a mesa.

A parte difícil não é o OAuth em si; são as cinco pequenas especificações que o fluxo de autenticação MCP compõe juntos: OAuth 2.1 (RFC 9700), PKCE (RFC 7636), Dynamic Client Registration (RFC 7591), Indicadores de Recursos (RFC 8707) e Metadados de Recursos Protegidos. Cada um é pequeno; a fiação é onde as equipes ficam presas. Aqui está o caminho, em ordem.

Etapa 1: veicular um documento de metadados de recursos protegidos

O arquivo PRM informa aos clientes onde está seu servidor de autorização, quais escopos você aceita e quais identificador de recurso para colocar no aud alegar. Hospede-o em /.well-known/oauth-protected-resource na mesma origem do seu endpoint MCP:

O authorization_servers list é o salto de descoberta. Os clientes buscam seu PRM, siga a primeira entrada do documento de metadados AS e crie o URL de autorização a partir daí. Mantenha a lista com uma entrada, a menos que você administre uma federação; múltiplos emissores confundem o cliente e nada nas especificações exige isso.

Etapa 2: publicar os metadados do servidor de autorização

Seu provedor de identidade (Auth0, Okta, Clerk, Cloudflare Access ou Hydra auto-hospedado) atende os metadados AS em /.well-known/oauth-authorization-server. Os clientes MCP consomem para aprender os pontos de extremidade de autorização e token, os tipos de concessão suportados e a localização do JWKS para verificação de token:

Três campos que as especificações exigem: code_challenge_methods_supported deve incluir S256; grant_types_supported deve incluir authorization_code e refresh_token; registration_endpoint deve estar presente se você oferece suporte a clientes dinâmicos. Sinto falta de qualquer um e Claude Desktop sinalizará o servidor como não compatível durante a configuração.

Etapa 3: gerar um par PKCE no cliente

PKCE tem 20 linhas de código do cliente e elimina a classe de interceptação de código de autorização de ataque. Gere 32 bytes aleatórios, codifique-os em base64url em um verificador, SHA-256 o verificador em um desafio e envie o desafio com a solicitação de autorização:

O resource O parâmetro (RFC 8707) é aquele que a maioria das implementações perde. Sem nele, um token criado para o seu servidor MCP pode ser reproduzido em qualquer outra API que confie no mesmo emissor; com isso, o aud reivindicação fixa o token ao seu identificador de recurso e nada mais aceita isso.

Passo 4: Troque o código por tokens

Após o redirecionamento de volta, o cliente envia o código mais o verificador original para o token ponto final. O servidor de autorização recalcula o SHA-256 do verificador e o compara com o desafio armazenado; se corresponderem, você receberá um token de acesso:

Armazene o token de atualização em armazenamento seguro (Keychain, Windows Credential Manager, Linux libsecret) e retire o verificador do armazenamento da sessão no momento em que a troca for bem-sucedida. Acesso os tokens duram de 5 a 60 minutos; os tokens de atualização duram mais, mas ainda devem girar durante o uso.

Etapa 5: verifique o token do portador em cada solicitação MCP

O HTTP streamable simplifica a verificação do token: cada solicitação HTTP carrega o Authorization cabeçalho, para que seu servidor MCP o verifique no middleware antes despachando a chamada da ferramenta. Busque o JWKS uma vez, armazene-o em cache e valide o emissor, o público e expiração em cada chamada:

As três afirmações que detectam bugs reais: iss fixa o emissor; aud fixa o recurso (evita a reprodução entre recursos); exp captura tokens obsoletos. Não aceite tokens sem estes; “Eu validei o assinatura" não é o mesmo que "Eu validei as reivindicações".

Etapa 6: coloque cada ferramenta nos escopos declarados por suas anotações

OAuth 2.1 sem design de escopo oferece acesso binário: o cliente pode chamar todas as ferramentas ou nenhum. O sistema de anotação MCP preenche essa lacuna, permitindo que cada ferramenta declare os escopos que deseja necessidades. O manipulador lê as anotações e os escopos do token no momento da invocação:

Mantenha os escopos destrutivos e somente leitura separados. Um usuário que concedeu tools:read para executar um relatório semanal não deve ser capaz de executar send_email do mesmo token. Claude Desktop e Cursor exibem escopos solicitados na tela de consentimento, então a divisão faz o UX é honesto sobre o que o cliente pode fazer.

Etapa 7: suporte ao registro dinâmico de clientes

O registro dinâmico de cliente permite que um cliente MCP se registre automaticamente em seu servidor de autorização sem um humano preenchendo um formulário. Cursor ou Claude Desktop POSTs uma solicitação de registro, recebe um client_ide executa o fluxo OAuth imediatamente:

Esta é a parte que move seu servidor MCP de "colar uma chave de API em um arquivo de configuração" para "clique em Conectar no Cursor e conceda acesso." Vale o trabalho se o seu servidor for público; ignorável se você enviar apenas para um pequeno conjunto de clientes conhecidos.

Verifique o fluxo completo de ponta a ponta

Uma vez que as peças estejam no lugar, uma chamada de ferramenta MCP completa se parece com qualquer outra chamada de ferramenta autenticada pelo portador. Solicitação HTTP:

Se você ver 401 com WWW-Authenticate: Bearer resource_metadata="...", o cliente sabe onde descobrir sua configuração de autenticação e executar novamente o fluxo. Esse cabeçalho é o handshake que torna possível a atualização e reconexão silenciosa do token após uma revogação.

Coloque o URL do PRM no WWW-Authenticate cabeçalho em cada resposta 401. O PCM spec torna esta a dica de descoberta canônica; clientes que veem um fallback 401 não anotado a solicitar ao usuário uma chave de API, que é exatamente o fluxo que o OAuth 2.1 está tentando substituir.

Folha de referências do design do escopo

Escopo	Capas	Concessão padrão
`tools:read`	Liste as ferramentas disponíveis, leia as descrições	Sempre concedido mediante consentimento
`tools:invoke:safe`	Chamadas de ferramentas idempotentes e somente leitura (pesquisas, análises)	Concedido por consentimento do usuário
`tools:invoke:destructive`	Chamadas de ferramentas mutantes (enviar e-mail, criar pedido)	Requer consentimento explícito por sessão
`resources:read`	Acesso somente leitura a recursos expostos	Concedido por padrão de recurso
`prompts:read`	Listar e ler prompts definidos pelo servidor	Concedido mediante consentimento

Principais conclusões

OAuth 2.1 requer PKCE. Não é bom ter; todo fluxo de código de autenticação carrega um verificador e desafio ou falha na conformidade com as especificações.
PRM em /.well-known/oauth-protected-resource é o ponto de entrada. Os clientes descobrem sua configuração de autenticação a partir desse URL; ignore-o e os clientes não poderão configurar automaticamente.
Use o resource parâmetro (RFC 8707). Fixa o público do token ao seu servidor MCP para que um token vazado não possa ser reproduzido em outras APIs.
Valide emissor, público, vencimento, escopo. Verificações de assinatura por si só, deixe reprodução entre recursos.
Divida escopos destrutivos. tools:read, tools:invoke:safe, e tools:invoke:destructive dar aos usuários o consentimento UX que eles esperam das permissões do sistema operacional.
O registro dinâmico do cliente desbloqueia instalações sem configuração. Pague o custo de implementação uma vez; cada novo cliente MCP se beneficia para sempre.

Servidor MCP hospedado em Botoi em api.botoi.com/mcp segue o mesmo padrão. Navegue pelo Documentos de configuração do MCP para configurações de Claude Desktop, Claude Code, Cursor, VS Code e Windsurf. Para a assinatura do JWT e primitivas de verificação que o middleware acima usa, consulte o Pontos de extremidade da API JWT nos documentos interativos.

FAQ

Por que PKCE para MCP quando os agentes não são navegadores?: PKCE (Proof Key for Code Exchange) vincula o código de autorização a um segredo criptográfico único que apenas o cliente inicial conhece. No contexto do MCP, o invasor não é uma extensão maliciosa do navegador; é um agente desonesto ou um código de autorização roubado flutuando em um log de terminal. PKCE significa que um código interceptado não pode ser resgatado sem o verificador de código original. OAuth 2.1 requer PKCE para cada fluxo de código de autorização, incluindo clientes confidenciais, portanto o MCP apenas segue as especificações.
O que é um documento de metadados de recursos protegidos?: Um documento PRM é um arquivo JSON servido em /.well-known/oauth-protected-resource que informa aos clientes OAuth onde reside o servidor de autorização, quais escopos o recurso aceita e qual identificador de recurso colocar na declaração aud. A especificação de autorização MCP adicionou PRM para que um cliente MCP descubra sua configuração de autenticação sem configuração fora de banda. O cliente busca o PRM, segue a URLauthorization_servers até os metadados AS, executa a dança OAuth e chega ao seu servidor MCP com um token de portador válido.
Preciso de registro dinâmico de cliente?: Para servidores MCP públicos expostos a muitos clientes, sim. O registro dinâmico de cliente (RFC 7591) permite que um cliente MCP se registre automaticamente em seu servidor de autorização, receba um client_id e inicie o fluxo OAuth em uma viagem de ida e volta. Sem ele, cada usuário precisa criar manualmente um aplicativo em seu painel antes de poder conectar Claude ou Cursor. Para integrações internas ou na lista de permissões, um client_id pré-provisionado ainda funciona.
Onde fica o token ao portador durante a sessão?: No cabeçalho de autorização de cada solicitação MCP. O HTTP streamable torna isso limpo; cada solicitação carrega o token e seu servidor o verifica no middleware antes de despachar a chamada da ferramenta. Tokens de acesso de curta duração (5 a 60 minutos) com tokens de atualização mantidos pelo cliente minimizam o raio de explosão de uma linha de log vazada. Nunca incorpore o token na URL; logs e proxies capturam URLs rotineiramente.
Como os escopos da ferramenta MCP se comparam aos escopos do OAuth?: O MCP se baseia na autorização baseada em função: um token carrega escopos como ferramentas:read, ferramentas:invoke:safe ou ferramentas:invoke:destructive, e anotações de ferramentas individuais declaram quais escopos são necessários. Os escopos são mapeados individualmente para escopos OAuth, para que você possa usar o mesmo design de escopo que já possui para uma API REST. A nova peça são anotações em nível de ferramenta no lado do MCP; eles tornam a decisão de autorização visível no registro da ferramenta, não apenas no código do manipulador.

Comece a construir com botoi

150+ endpoints de API para consultas, processamento de texto, geração de imagens e utilitários para desenvolvedores. Plano gratuito, sem cartão de crédito.

Ver documentação da API Ver todas as ferramentas