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

Há poucos dias (18 de junho de 2025), a equipa do MCP (Model Context Protocol) lançou a versão mais recente da Especificação MCP (2025-06-18). Esta atualização inclui uma alteração fundamental na especificação de autenticação. Os servidores MCP já não irão emitir tokens de acesso como um Servidor de Autorização. Em vez disso, vão consumir tokens de acesso e fornecer recursos como um Servidor de Recursos.

Como um dos mantenedores do MCP Auth (uma biblioteca plug-and-play de autenticação de Servidor MCP), implementei o suporte à especificação de autenticação MCP mais recente neste projeto. Com base na minha experiência prática, vou mostrar como implementar funcionalidades de autenticação para o teu Servidor MCP que cumpram a especificação atual.

Este artigo vai ajudar-te a:

• Perceber como funciona a autenticação MCP segundo a nova especificação
• Esclarecer o que os Servidores MCP têm de implementar como Servidores de Recursos de acordo com os requisitos da especificação
• Guiar-te na implementação de suporte de autenticação que cumpra as exigências mais recentes para o teu Servidor MCP
• Identificar pontos negligenciados e questões de segurança na implementação da especificação de autenticação MCP

Nota que este artigo:

• Pressupõe que os leitores têm conhecimentos básicos de JWT (JSON Web Token). O artigo não aborda em detalhe a estrutura JWT, verificação de assinaturas ou outros conceitos básicos. Para detalhes específicos, consulta a Auth Wiki - JWT
• Não aprofunda várias RFCs das quais a especificação MCP depende. O artigo só apresenta implementações em conformidade com esses requisitos RFC
• Não cobre detalhes de implementação e interação do Cliente MCP e de Autorizações. Estes costumam ser implementados por clientes LLM e provedores de servidor de autorização que dão suporte ao MCP segundo a especificação. Os desenvolvedores de Servidor MCP normalmente não precisam e não podem interferir nestas implementações. Para detalhes, vê OAuth Client e Authorization Server
• Assume que todos os tokens de acesso mencionados no artigo são JWT, que é o formato mais usado atualmente. Outros formatos devem ser usados conforme a documentação do respectivo provedor de autenticação.

Como funciona a autenticação MCP?#

De acordo com a especificação de autenticação MCP mais recente, o fluxo é ilustrado neste diagrama:

1. O Cliente MCP pede recursos ao Servidor MCP em https://github-tools.com. Como o utilizador ainda não iniciou sessão, o header de autorização HTTP deste pedido não contém um token de acesso correspondente ao utilizador.

2. O Servidor MCP não encontra token de acesso no header de autorização do pedido do Cliente MCP. Por isso, devolve um erro HTTP 401 ao Cliente MCP. A resposta inclui um cabeçalho WWW-Authenticate, que contém o URL dos metadados de recursos do Servidor MCP (valor do campo resource_metadata).

3. O Cliente MCP extrai o valor de resource_metadata do cabeçalho WWW-Authenticate (por exemplo: https://github-tools.com/.well-known/oauth-protected-resource). Depois, o Cliente MCP pede os metadados de recursos fornecidos pelo Servidor MCP como Servidor de Recursos. Estes metadados incluem conteúdos como authorization_servers e scopes_supported, ajudando o Cliente MCP a perceber como obter o token de acesso necessário para aceder ao Servidor MCP, ou seja, de que servidor de autorização irá obter um token com permissões específicas.

4-8. O Cliente MCP pede informações de metadados ao servidor de autorização com base no URL obtido dos metadados de recursos. Em seguida, realiza o fluxo de autorização OAuth 2.1 com o servidor de autorização e obtém um token de acesso.

9. O Cliente MCP transporta o token de acesso obtido do servidor de autorização e faz novo pedido de recursos ao Servidor MCP.

10. O Servidor MCP devolve o recurso pedido após verificar que o token é válido. Depois, a comunicação entre Cliente MCP e Servidor MCP continuará com o token válido.

A seguir, vamos explicar como implementar o mecanismo de autenticação do servidor MCP passo a passo com base neste fluxo.

Gerir pedidos não autorizados: devolver erro 401 e header WWW-Authenticate#

Como mostra o fluxo acima, quando o Cliente MCP envia um pedido sem token de acesso, o Servidor MCP devolve um erro HTTP 401 Não autorizado com o cabeçalho WWW-Authenticate contendo o URL para obter os metadados de recurso do Servidor MCP.

De acordo com os requisitos de gestão de erros da especificação de autenticação MCP, além de pedidos do Cliente MCP que não tragam tokens, quando o Servidor MCP recebe um token inválido também deve devolver erro 401 com um cabeçalho WWW-Authenticate.

Já sabemos quando devolver um erro 401, mas como construir o cabeçalho WWW-Authenticate retornado?

Segundo RFC9728 Secção 5.1, o cabeçalho WWW-Authenticate deve incluir o parâmetro resource_metadata para apontar o URL dos metadados protegidos do recurso.

O seu formato básico é:

Aqui, Bearer é o esquema de autenticação, indicando que é necessário um token bearer para aceder a recursos protegidos pelo OAuth 2.0 (ver: documentação MDN). O valor de resource_metadata é o URL integral do endpoint de metadados fornecido pelo teu Servidor MCP.

A implementação em código é algo como:

Quando o Cliente MCP recebe este erro 401 vai aceder aos metadados do Servidor MCP pelo valor de resource_metadata no cabeçalho. Com base nos dados dos metadados, irá pedir autorização ao servidor indicado para obter um token válido.

Sabemos agora quando devolver erro 401 e que é preciso devolver um URL de resource_metadata. Falta saber como construir este URL e que dados esses metadados devem conter. Vamos abordar isso a seguir.

Implementar mecanismo de descoberta de metadados de recurso#

Segundo o fluxo de autenticação MCP, após o Cliente receber erro 401, pede imediatamente os metadados ao Servidor MCP. Por isso, o Servidor MCP enquanto Servidor de Recursos deve implementar esse mecanismo.

Determinar o caminho do endpoint de metadados#

No sistema OAuth, usamos URLs para identificar endereços de recursos. Este endereço denomina-se "indicador de recurso". Segundo as regras RFC9728, os metadados devem estar sob um caminho /.well-known específico.

Se o teu Servidor MCP (tipo https://github-tools.com) apenas fornece um serviço, o endpoint de metadados será:

Se prestas vários serviços MCP distintos num host, cada serviço deve ter endpoint de metadados independente. Por exemplo, a plataforma de empresa https://api.acme-corp.com disponibiliza:

• https://api.acme-corp.com/github - Integração GitHub
• https://api.acme-corp.com/slack - Integração Slack
• https://api.acme-corp.com/database - Serviço de consulta à base de dados

Os endpoints de metadados 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

Vantagem deste design: cada serviço pode ter diferentes permissões e configurações de servidor de autorização. Por exemplo:

• GitHub usa OAuth GitHub, precisa das permissões github:read, github:write
• Slack usa OAuth Slack, precisa slack:channels:read, slack:messages:write
• Base de dados usa servidor interno, precisa db:query

Podemos resumir assim os endpoints dos metadados:

Obtém-se o endpoint a partir do identificador do recurso:

Construir resposta dos metadados#

Após determinado o path do endpoint, é preciso devolver metadados em formato JSON compatíveis com as regras da RFC9728.

Na implementação, deves focar em quatro campos críticos.

Primeiro, resource, que é o identificador do recurso, igual ao endereço do recurso a aceder pelo Cliente MCP.

Depois, authorization_servers, array que especifica de que servidores de autorização o Cliente MCP pode requerer tokens. Segundo o RFC 9728 é opcional, mas na especificação MCP é obrigatório: o cliente tem de saber de que servidor de autorização pedir o token, caso contrário não conclui o fluxo OAuth.

Segue-se o campo scopes_supported, com as permissões aceites por este Servidor de Recursos.

Por fim, bearer_methods_supported indica ao Cliente como deve enviar tokens. Normalmente ["header"], ou seja, o token vai no header Authorization HTTP.

Um exemplo completo para o servidor MCP em https://github-tools.com:

Assim, o Cliente MCP percebe que quer aceder ao recurso https://github-tools.com, precisa de pedir token ao https://auth.github-tools.com, pode requerer escopos github:read, github:write, repo:admin, devendo enviar o token pelo header Authorization.

Na maioria dos casos bastam estes quatro campos para o Cliente MCP funcionar corretamente. Para configurações mais complexas, consulta a lista completa no RFC9728.

Validar tokens de acesso#

Depois de receber o token do servidor de autorização, o Cliente MCP vai trazer esse token num pedido ao Servidor MCP.

Na validação dos tokens, o Servidor MCP deve prestar atenção a:

1. Validar o token de acordo com a configuração do Servidor MCP e não só pelas informações transportadas no token.
2. Verificar se o audience do token coincide com o próprio Servidor MCP, garantindo que o token foi obtido para os recursos deste servidor.
3. Validar corretamente o scope.

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

Quando o Servidor MCP recebe um token, porque este traz informação do servidor de autorização (issuer), alguns devs vão buscar todos os dados de verificação conforme o issuer do token. Isto, sobretudo quando há múltiplos servidores de autorização como nos metadados:

Neste caso, alguns devs extraem o issuer do token não verificado para obter os dados de validação. Mas um atacante pode montar um servidor de autorização falso e emitir um token falso para o Servidor MCP. Se o developer aceitar tokens de servidores desconhecidos (com base apenas no issuer do token), esta verificação passa indevidamente.

Portanto, a forma correta é:

• Se só existe um servidor de autorização: validar apenas segundo a configuração backend
• Se existem vários servidores de autorização: extrair o issuer do token não verificado e procurar o servidor correspondente nas configurações do Servidor MCP. Se não existir, recusar o token

Lembra-te de validar rigorosamente o issuer do token.

Usando a biblioteca jose JWT como exemplo:

Validação do audience do token#

A secção de Binding e Validação de Audience do Token na especificação indica: quando o cliente pede token ao servidor de autorização, deve especificar para que recurso o token será usado. O Servidor MCP tem também de verificar se o audience do token corresponde a si mesmo.

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

1. Pedido do cliente: quando pede token, especifica o parâmetro resource, indicando o servidor de recursos alvo (tipo https://github-tools.com)

2. Emissão do token: o endereço do recurso indicado fica na audience do token JWT

3. Validação: o Servidor MCP, ao receber o token, verifica se a audience (campo aud) coincide com o seu identificador

Exemplo para o Servidor MCP em https://github-tools.com:

Esta validação de audience é essencial para evitar abusos de token. Sem ela, tokens obtidos noutros serviços poderiam ser aceites inadvertidamente pelo teu servidor.

Validação de scope#

Alguns Servidores MCP gerem permissões para recursos internos, pois utilizadores distintos poderão ter diferentes escopos de permissões.

Assim, depois do token passar a validação, verifica-se se possui o scope necessário. Para isso, verifica se o claim scope no token inclui a permissão para aceder ao recurso:

Segundo a especificação de autenticação MCP, se o token não tiver a permissão necessária, deve-se retornar 403 Forbidden.

Conclusão#

Depois desta explicação, já deves conseguir implementar autenticação para o teu Servidor MCP conforme as últimas especificações. Recorda estes pontos-chave: valida tokens de forma segura, configura corretamente os metadados e verifica sempre o audience.

Se estás a construir um Servidor MCP, experimenta a biblioteca MCP Auth. Já traz implementadas todas as funcionalidades referidas aqui e pode ajudar-te a integrar autenticação rapidamente.

Participa na discussão no GitHub para contribuir para o avanço do ecossistema MCP.