Tutorial
Como autenticar Servidores MCP usando OAuth 2.1 no Claude?
Para autenticar servidores MCP no transporte HTTP, a especificação oficial exige configurar o servidor MCP como um OAuth 2.1 Resource Server. O servidor intercepta requisições HTTP e valida tokens Bearer emitidos por um Provedor de Identidade compatível com PKCE (S256). O cliente MCP atua em nome do usuário final, solicitando a autorização prévia antes que o Claude execute ferramentas ou acesse dados sensíveis.
A expansão do Model Context Protocol (MCP) para ambientes Web e arquiteturas distribuídas trouxe a necessidade crítica de proteger ferramentas e recursos remotos contra acessos não autorizados. Enquanto integrações locais baseadas no transporte stdio contam com o isolamento de processos do sistema operacional, servidores MCP que operam em redes HTTP exigem mecanismos robustos de identidade para garantir o controle de acesso corporativo aos modelos do ecossistema Anthropic.
Por que usar OAuth 2.1 na arquitetura de Servidores MCP?
À medida que sistemas baseados em inteligência artificial assumem tarefas autônomas, a simples utilização de chaves de API estáticas compartilhadas torna-se um risco substancial de segurança. A adoção da especificação OAuth 2.1 para o protocolo MCP resolve esse problema estabelecendo papéis bem definidos para a autenticação em transporte HTTP:
- Servidor MCP como Resource Server: Valida a autenticidade e os escopos dos tokens de acesso em cada chamada de ferramenta (tool call) ou recurso.
- Cliente MCP como OAuth Client: Solicita autorização ao usuário e obtém o token de acesso para realizar chamadas remotas.
- Provedor de Identidade (Authorization Server): Autentica o usuário e emite credenciais temporárias com escopos delimitados.
Com essa estrutura, a organização consegue auditabilidade precisa sobre quais ações o assistente Claude executou em nome de cada colaborador específico, além de viabilizar a revogação instantânea de permissões sem impactar outros serviços.
Como funciona o fluxo de autorização no Model Context Protocol?
O fluxo de autenticação HTTP no MCP segue o padrão OAuth 2.1 Authorization Code com PKCE (Proof Key for Code Exchange), eliminando o armazenamento de senhas ou credenciais de longo prazo pelo cliente. A sequência operacional ocorre da seguinte forma:
- Requisição Inicial do Cliente: O cliente MCP tenta acessar um recurso protegido sem token ou com token expirado no servidor HTTP.
- Desafio HTTP 401: O servidor MCP responde com status
401 Unauthorizede o cabeçalhoWWW-Authenticate, indicando os metadados do servidor de autorização (RFC 8414 / RFC 9728). - Autenticação Interativa: O cliente redireciona o usuário ao provedor de identidade para conceder o consentimento das permissões requeridas.
- Troca com PKCE: Após a aprovação, o cliente recebe o código de autorização e o troca por um token de acesso Bearer utilizando o desafio de chave
S256. - Execução de Chamadas: O cliente reenvia a requisição contendo o cabeçalho
Authorization: Bearer <token>, permitindo que o Claude interaja com as ferramentas do servidor.
Documentações e especificações detalhadas do fluxo podem ser consultadas nas guias oficiais de desenvolvimento do Claude.
Como implementar a validação de token no servidor HTTP?
Na construção de um servidor MCP em Python ou TypeScript, a validação do token deve ocorrer no middleware do transporte HTTP antes de repassar a mensagem JSON-RPC para o manipulador do protocolo. Veja os componentes essenciais dessa validação:
| Etapa de Checagem | Requisito da Especificação | Descrição Operacional |
|---|---|---|
| Verificação da Assinatura | Algoritmos RS256/ES256 (JWKS) | Valida a autenticidade do token utilizando as chaves públicas divulgadas pelo Authorization Server. |
| Checagem de Expiração | Reclamação exp (Epoch Time) | Rejeita requisições se o horário atual ultrapassar o tempo limite de validade do token. |
| Validação de Emissor | Reclamação iss (Issuer URL) | Garante que o token foi emitido estritamente pelo servidor de identidade confiável. |
| Verificação de Escopos | Reclamação scope ou scp | Confirma se o token possui os escopos necessários para a ferramenta ou recurso individual solicitado. |
Em caso de falha em qualquer uma dessas validações, o servidor deve interromper o processamento da chamada e retornar um erro HTTP correspondente imediatamente.
Qual a diferença entre autenticação HTTP e transporte Stdio?
A escolha entre o transporte local (stdio) e remotos baseados em rede (HTTP/SSE) impacta diretamente a estratégia de credenciais empregada no projeto:
- Transporte Stdio (Local): Recomendado para ferramentas de desenvolvimento e CLI como o Claude Code. As credenciais não utilizam o fluxo OAuth interativo, devendo ser injetadas diretamente via variáveis de ambiente configuradas no arquivo JSON local do cliente.
- Transporte HTTP / WebSockets (Remoto): Obrigatório para infraestruturas multi-tenant ou microsserviços compartilhados. Exige a implementação completa da especificação OAuth 2.1 com tokens renováveis para isolar o acesso por usuário.
Quais são as boas práticas de segurança para produção?
Para garantir um ambiente resiliente e em conformidade com as diretrizes do Model Context Protocol, adote as seguintes práticas recomendadas ao implantar servidores MCP autenticados:
- Garanta o uso estrito de HTTPS: Nunca exponha endpoints HTTP não criptografados, pois tokens Bearer trafegados em texto plano podem ser interceptados por redes intermediárias.
- Aplique o Princípio do Menor Privilégio: Defina escopos granulares para cada ferramenta MCP em vez de utilizar escopos globais de leitura e escrita.
- Implemente Revogação de Token: Mantenha uma rotina de verificação para listas de revogação ou utilize tokens de vida curta associados a tokens de atualização (Refresh Tokens).
- Exija PKCE Obrigatório: Configure o servidor de autorização para rejeitar requisições de clientes públicos que não utilizem o desafio de chave
S256.
Leia mais no site
- Como implementar RBAC e Filtragem de Ferramentas em Servidores MCP?
- Como implementar Autenticação OAuth em Servidores MCP para o Claude?
- Como implementar Human-in-the-Loop em agentes com Claude?
- Como criar um MCP Client customizado para integrar o Claude em seu app?
- MCP SDK TypeScript vs. Python: Qual a melhor stack para servidores?
Perguntas frequentes
É possível usar OAuth 2.1 em servidores MCP operando via Stdio?
Não, o fluxo OAuth 2.1 se aplica exclusivamente a transportes baseados em HTTP, como Server-Sent Events (SSE) ou WebSockets. Em conexões estritamente locais via stdio, a autenticação deve ser tratada passando chaves de API ou tokens diretamente através de variáveis de ambiente configuradas no arquivo de configuração do cliente Claude.
Qual a função do mecanismo PKCE na autorização de clientes MCP?
O Proof Key for Code Exchange (PKCE) com algoritmo S256 é obrigatório na especificação OAuth 2.1 do MCP para prevenir ataques de interceptação de código de autorização. Ele garante que apenas a instância legítima do cliente MCP que iniciou o fluxo de login possa trocar o código pelo token de acesso final.