Português (Brasil)

mcp
mcp-auth

Guia de implementação de autenticação do servidor MCP: usando a especificação mais recente

Fornece pontos-chave de implementação para a conformidade da autenticação do servidor MCP com a especificação de 18/06/2025.

Yijun

Developer

6/30/2025

Pare de perder semanas com autenticação de usuários

Lance aplicativos seguros mais rapidamente com o Logto. Integre a autenticação de usuários em minutos e concentre-se no seu produto principal.

Começar

Alguns dias atrás (18 de junho de 2025), a equipe do MCP (Model Context Protocol) lançou a versão mais recente da MCP Spec (2025-06-18). Esta atualização inclui uma alteração importante na especificação de autenticação. Servidores MCP não vão mais emitir access tokens como um Authorization Server. Em vez disso, eles vão consumir access tokens e fornecer recursos como um Resource Server.

Como um dos mantenedores do MCP Auth (uma biblioteca plug-and-play de autenticação para Servidores MCP), implementei suporte para a especificação mais recente de autenticação MCP neste projeto. Com base na minha experiência prática, vou te mostrar como implementar recursos de autenticação para seu Servidor MCP que estejam em conformidade com a especificação mais recente.

Este artigo vai te ajudar a:

Entender como funciona a autenticação MCP segundo a nova especificação
Esclarecer o que servidores MCP precisam implementar como Resource Server de acordo com a especificação
Oferecer orientações para implementar suporte de autenticação que atenda à nova especificação em seu Servidor MCP
Identificar pontos pouco notados e questões de segurança ao implementar a especificação

Observe que este artigo:

Assume que você possui conhecimentos básicos sobre JWT (JSON Web Token). Não abordaremos estrutura, verificação de assinatura e outros conceitos básicos de JWT em detalhes. Para detalhes específicos, veja Auth Wiki - JWT
Não aprofunda os vários RFCs dos quais a especificação MCP depende. Foca apenas nas implementações compatíveis com esses requisitos
Não aborda detalhes de implementação e interação do MCP Client e Authorization Server. Esses geralmente são implementados por clientes LLM e provedores de servidores de autorização que suportam MCP conforme a especificação. Desenvolvedores de servidor MCP não precisam e não podem interferir nessas implementações. Para detalhes específicos, consulte OAuth Client e Authorization Server
Todos os access tokens mencionados supõe-se que sejam JWT, formato mais comum no mercado. Outros formatos devem seguir a documentação do respectivo provedor de servidor de autorização.

Como funciona a autenticação MCP?

De acordo com a última especificação de autenticação MCP, o fluxo de autenticação é demonstrado neste diagrama:

O Cliente MCP requisita recursos do Servidor MCP em https://github-tools.com. Como o usuário ainda não fez login, o cabeçalho HTTP de autorização dessa requisição não traz um access token que represente o usuário.
O Servidor MCP não encontra um access token no cabeçalho de autorização da requisição do MCP Client. Ele retorna um erro HTTP 401 ao MCP Client. Esta resposta de erro inclui um header WWW-Authenticate, que contém a URL da metadata do recurso do Servidor MCP (o valor do campo resource_metadata).
O Cliente MCP extrai o valor de resource_metadata do header WWW-Authenticate retornado (por exemplo: https://github-tools.com/.well-known/oauth-protected-resource). Então o Cliente requisita a metadata do recurso oferecida pelo Servidor MCP como Resource Server nesse endereço. Essa metadata inclui conteúdos como authorization_servers e scopes_supported, ajudando o Cliente a entender de onde obter um access token com as permissões corretas para acessar o Servidor MCP.

4-8. O Cliente MCP requisita informações de metadata do servidor de autorização baseado na URL de metadata obtida da metadata do recurso. Depois, o Cliente executa um fluxo OAuth 2.1 com o servidor de autorização e recebe um access token após a autorização.

O Cliente MCP leva o access token obtido do servidor de autorização e faz nova requisição de recurso ao Servidor MCP.
O Servidor MCP retorna o recurso solicitado após checar que o token é válido. Depois disso, a comunicação entre Cliente e Servidor MCP prosseguirá com o token válido.

A seguir, explicaremos como implementar esse mecanismo de autenticação do servidor MCP passo a passo com base no fluxo do MCP.

Trate requisições não autorizadas: retorne erro 401 e WWW-Authenticate

Como mostrado no fluxo acima, quando o Cliente MCP envia uma requisição sem access token ao Servidor MCP, o servidor deve retornar HTTP 401 Unauthorized com o header WWW-Authenticate contendo a URL da metadata do recurso.

De acordo com os requisitos de tratamento de erros da especificação MCP, além de requisições sem access token, quando o Servidor MCP recebe um token inválido, ele também deve retornar erro 401 com o header WWW-Authenticate.

Sabendo quando retornar erro 401, como devemos construir esse header?

Segundo RFC9728 Seção 5.1, o header WWW-Authenticate precisa incluir o parâmetro resource_metadata indicando a URL da metadata do recurso protegido.

Seu formato básico será:

Aqui, Bearer é o esquema de autenticação, indicando que é necessário um bearer token para acessar o recurso protegido pelo OAuth 2.0 (consulte: Documentação MDN). O valor de resource_metadata é a URL completa do endpoint de metadata do recurso fornecida pelo Servidor MCP.

A implementação no código pode ser assim:

Quando o Cliente MCP recebe esse erro 401, ele irá acessar a metadata do recurso via o valor de resource_metadata no header. Em seguida, usando as informações da metadata, iniciará um fluxo de autorização no servidor especificado para buscar o access token necessário.

Já entendemos quando retornar erro 401 e a necessidade de retornar uma URL de resource_metadata. Mas ainda precisamos saber como construir essa URL e o que a metadata precisa conter. Abordaremos isso a seguir.

Implemente o mecanismo de descoberta da metadata do recurso

Pelo fluxo do MCP, após o Cliente MCP receber o erro 401, ele solicita imediatamente a metadata do recurso. Portanto, o servidor MCP como Resource Server deve implementar essa descoberta.

Defina o caminho da URL do endpoint de metadata

No sistema OAuth, usamos URLs para identificar recursos. Este endereço é conhecido como "resource indicator". Pelas regras do RFC9728, a metadata do recurso deve estar hospedada em um caminho específico /.well-known.

Se seu Servidor MCP (por exemplo, https://github-tools.com) oferece um serviço apenas, o endpoint deve ser:

Se você oferece vários serviços MCP diferentes em um mesmo host, cada serviço deve ter seu endpoint independente. Exemplo, a plataforma https://api.acme-corp.com oferece os serviços:

https://api.acme-corp.com/github - Serviço de integração com GitHub
https://api.acme-corp.com/slack - Serviço de integração com Slack
https://api.acme-corp.com/database - Serviço de consulta a banco de dados

Os endpoints de metadata serão:

https://api.acme-corp.com/.well-known/oauth-protected-resource/github
https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Essa abordagem permite que cada serviço tenha escopos de permissão e configurações de autorização diferentes. Exemplo:

O serviço do GitHub usa OAuth próprio do GitHub, requer permissões github:read, github:write
O serviço do Slack usa OAuth do Slack, requer permissões slack:channels:read, slack:messages:write
O serviço de banco usa servidor de autorização interno da empresa, requer permissão db:query

Portanto, URLs de endpoint de metadata seguem o padrão:

Podemos obter a URL do endpoint de metadata assim a partir do resource indicator:

Monte a resposta de metadata do recurso

Após definir a URL do endpoint, fazemos ele retornar metadata em JSON conforme RFC9728.

Na prática, precisamos focar em quatro campos fundamentais.

Primeiro, o campo resource, identificador do recurso, deve ser igual ao endereço a ser acessado pelo Cliente MCP.

Depois, o campo authorization_servers, array que especifica de quais servidores de autorização o Cliente MCP deve pedir um access token. Segundo o OAuth 2.0 Protected Resource Metadata (RFC 9728), esse campo é opcional. Mas na especificação MCP ele é obrigatório, pois o Cliente precisa saber exatamente em qual servidor pedir autorização. Sem isso, o Cliente não finaliza o fluxo OAuth.

O campo scopes_supported lista todos os escopos de permissão que este servidor suporta.

Por fim, o campo bearer_methods_supported informa como o Client deve enviar os access tokens para o servidor. Normalmente, usamos ["header"], que significa que, após obter o token, o Client deve enviá-lo via header Authorization do HTTP.

Vamos ver um exemplo. Suponha que queremos configurar metadata para o servidor MCP https://github-tools.com:

Essa configuração revela ao Cliente diversas informações importantes: ele quer acessar https://github-tools.com, deve buscar o access token em https://auth.github-tools.com, pode solicitar permissões como github:read, github:write, repo:admin, e precisa passar o token pelo header Authorization.

Na maioria dos casos de uso, esses quatro campos já são suficientes para o funcionamento do Cliente MCP. Se precisar de configurações avançadas, veja a lista completa no RFC9728.

Valide os access tokens

Depois que o Cliente MCP consegue um access token do authorization server, ele vai utilizá-lo para acessar o Servidor MCP.

Na validação de tokens, o servidor MCP deve observar o seguinte:

Ao realizar a validação básica, valide o token segundo a configuração do servidor, e não usando os dados trazidos pelo próprio token.
Valide se o "audience" do token é o próprio servidor MCP, garantindo que o token foi mesmo emitido para acessar aquele recurso.
Faça a checagem correta dos escopos.

Use a configuração do MCP Server para validar tokens

Quando o servidor recebe um access token, certos desenvolvedores usam imediatamente o campo issuer do token não verificado para extrair informações do authorization server usado. Isso é comum quando há múltiplos servidores de autorização na metadata, por exemplo:

Nesse caso, o desenvolvedor pode extrair o issuer de um token falso e confiar, sem querer, num servidor de autorização malicioso, que teria criado o token. Assim, a validação permitiria tokens falsos.

A maneira correta é:

No caso de apenas um servidor de autorização configurado: valide o token segundo a configuração back-end
No caso de múltiplos servidores: extraia issuer do token não verificado, procure esse servidor apenas nas opções já configuradas pelo Servidor MCP. Se não encontrar, rejeite o token

Sempre valide estritamente o issuer do token.

Usando a biblioteca jose JWT para exemplificar:

Valide o audience do token

Na seção Token Audience Binding and Validation da especificação MCP, está previsto que ao pedir um access token, o cliente deve informar para qual recurso o token será usado. O servidor MCP também precisa checar se esse audience confere.

Este mecanismo segue o padrão Resource Indicators for OAuth 2.0 (RFC 8707). Resumidamente:

Fase do pedido: Cliente MCP pede token do servidor de autorização, especifícando o parâmetro resource, dizendo para qual entidade ele usará esse token (exemplo: https://github-tools.com)
Emissão do token: O servidor de autorização vincula esse resource ao campo audience (ou aud) do JWT
Validação: O servidor MCP deve comparar esse audience com seu próprio identificador

Usando o exemplo https://github-tools.com:

Esta validação é crucial para a segurança. Se omitida, atacantes podem usar tokens destinados a outros serviços para tentar acessar o seu. Se o servidor não verificar o audience, aceitará tokens indevidos.

Validação de escopo

Alguns servidores MCP controlam permissões de acesso a recursos internos, já que usuários distintos têm escopos diferentes.

Assim, após validar o token, deve-se checar se ele oferece o escopo específico para o recurso desejado. Isso pode ser feito verificando se o scope do token inclui a permissão necessária:

Observe que pela especificação MCP, se o token não tiver o escopo necessário, deve-se retornar erro 403 Forbidden.

Conclusão

Com as orientações deste artigo, você conseguirá implementar autenticação em seu Servidor MCP compatível com a especificação mais recente. Lembre-se de alguns pontos-chave: valide tokens com segurança, configure corretamente a metadata e verifique rigorosamente o audience.

Se você está desenvolvendo um Servidor MCP, experimente a biblioteca MCP Auth. Ela já implementa todas as funcionalidades discutidas aqui e vai te ajudar a integrar autenticação com rapidez.

Fique à vontade para tirar dúvidas no GitHub. Vamos juntos fortalecer o ecossistema do MCP.

Como funciona a autenticação MCP?#

Trate requisições não autorizadas: retorne erro 401 e WWW-Authenticate#

Implemente o mecanismo de descoberta da metadata do recurso#

Defina o caminho da URL do endpoint de metadata#

Monte a resposta de metadata do recurso#

Valide os access tokens#

Use a configuração do MCP Server para validar tokens#

Valide o audience do token#

Validação de escopo#

Conclusão#

Como funciona a autenticação MCP?#

Trate requisições não autorizadas: retorne erro 401 e WWW-Authenticate#

Implemente o mecanismo de descoberta da metadata do recurso#

Defina o caminho da URL do endpoint de metadata#

Monte a resposta de metadata do recurso#

Valide os access tokens#

Use a configuração do MCP Server para validar tokens#

Valide o audience do token#

Validação de escopo#

Conclusão#

Como funciona a autenticação MCP?

Trate requisições não autorizadas: retorne erro 401 e WWW-Authenticate

Implemente o mecanismo de descoberta da metadata do recurso

Defina o caminho da URL do endpoint de metadata

Monte a resposta de metadata do recurso

Valide os access tokens

Use a configuração do MCP Server para validar tokens

Valide o audience do token

Validação de escopo

Conclusão

Como funciona a autenticação MCP?

Trate requisições não autorizadas: retorne erro 401 e WWW-Authenticate

Implemente o mecanismo de descoberta da metadata do recurso

Defina o caminho da URL do endpoint de metadata

Monte a resposta de metadata do recurso

Valide os access tokens

Use a configuração do MCP Server para validar tokens

Valide o audience do token

Validação de escopo

Conclusão