Pular para o conteúdo principal

Primeiros passos

Suporte à especificação de autorização MCP

Esta versão oferece suporte à especificação de autorização MCP (versão 2025-06-18).

SDK Python disponível

O MCP Auth também está disponível para Python! Confira o repositório do SDK Python para instalação e uso.

Escolha um provedor compatível com OAuth 2.1 ou OpenID Connect​

A especificação MCP possui requisitos específicos para autorização. O mecanismo de autorização é baseado em especificações consolidadas, implementando um subconjunto selecionado de seus recursos para garantir segurança e interoperabilidade, mantendo a simplicidade:

Essas especificações trabalham juntas para fornecer uma estrutura de autorização segura e padronizada para implementações MCP.

Você pode verificar a lista de provedores compatíveis com MCP para ver se seu provedor é suportado.

Instale o SDK MCP Auth​

pnpm add mcp-auth

Inicialize o MCP Auth​

O primeiro passo é definir seu identificador de recurso e configurar o servidor de autorização que será confiável para autenticação. O MCP Auth agora opera no modo servidor de recursos, conforme a especificação MCP atualizada que exige OAuth 2.0 Protected Resource Metadata (RFC 9728).

Se o seu provedor estiver em conformidade com:

Você pode usar a função integrada para buscar os metadados e inicializar a instância do MCP Auth:

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

// 1. Defina seu identificador de recurso e busque a configuração do servidor de autorização confiável.
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. Inicialize o MCPAuth no modo servidor de recursos.
// `protectedResources` pode ser um único objeto ou um array para múltiplos recursos.
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Se você estiver usando runtimes edge como Cloudflare Workers, onde o fetch assíncrono no topo não é permitido, use a descoberta sob demanda:

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

Para outras formas de configurar os metadados do servidor de autorização, incluindo URLs de metadados personalizados, transpile de dados ou especificação manual de metadados, confira Outras formas de configurar o MCP Auth.

Monte o endpoint de metadados do recurso protegido​

Para estar em conformidade com a especificação MCP atualizada, o MCP Auth monta o endpoint OAuth 2.0 Protected Resource Metadata (RFC 9728) no seu servidor MCP. Esse endpoint permite que os clientes descubram:

  • Quais servidores de autorização podem emitir tokens válidos para seus recursos protegidos
  • Quais escopos são suportados para cada recurso
  • Outros metadados necessários para validação adequada do token

O caminho do endpoint é determinado automaticamente pelo componente de caminho do seu identificador de recurso:

  • Sem caminho: https://api.example.com → /.well-known/oauth-protected-resource
  • Com caminho: https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

O servidor MCP agora atua como um servidor de recursos que valida tokens e fornece metadados sobre seus recursos protegidos, confiando inteiramente em servidores de autorização externos para autenticação e autorização.

Você pode usar o método fornecido pelo SDK para montar esse endpoint:

import express from 'express';

const app = express();

// Monte o router para servir os Metadados do Recurso Protegido.
// Para o recurso "https://api.example.com" → endpoint: /.well-known/oauth-protected-resource
// Para o recurso "https://api.example.com/notes" → endpoint: /.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

Use o middleware Bearer auth​

Depois que a instância do MCP Auth estiver inicializada, você pode aplicar o middleware Bearer auth para proteger suas rotas MCP. O middleware agora exige a especificação de qual recurso o endpoint pertence, permitindo a validação adequada do token:

Validação do público (Audience Validation)

O parâmetro audience é obrigatório pela especificação OAuth 2.0 para validação segura do token. No entanto, atualmente é opcional para manter a compatibilidade com servidores de autorização que ainda não suportam identificadores de recurso. Por motivos de segurança, sempre inclua o parâmetro audience quando possível. Versões futuras tornarão a validação do público obrigatória para total conformidade com a especificação.

Sempre valide os escopos

No OAuth 2.0, os escopos (Scopes) são o principal mecanismo de controle de permissões. Um token válido com o audience correto NÃO garante que o usuário tenha permissão para realizar uma ação — servidores de autorização podem emitir tokens com escopo vazio ou limitado.

Sempre use requiredScopes para garantir que o token contenha as permissões necessárias para cada operação. Nunca assuma que um token válido implica acesso total.

import express from 'express';

const app = express();

// Monte o router para servir os Metadados do Recurso Protegido.
app.use(mcpAuth.protectedResourceMetadataRouter());

// Proteja um endpoint de API usando a política específica do recurso.
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // Habilite a validação do público para segurança
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // Se o token for válido, `req.auth` é preenchido com suas reivindicações.
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

Nos exemplos acima, especificamos o tipo de token jwt e o identificador do recurso. O middleware validará automaticamente o token JWT contra os servidores de autorização confiáveis configurados para esse recurso específico e preencherá as informações do usuário autenticado.

info

Nunca ouviu falar de JWT (JSON Web Token) antes? Não se preocupe, você pode continuar lendo a documentação e explicaremos quando necessário. Você também pode conferir o Auth Wiki para uma introdução rápida.

Para mais informações sobre a configuração do Bearer auth, confira Configurar Bearer auth.

Recupere as informações de autenticação na sua implementação MCP​

Depois que o middleware Bearer auth for aplicado, você pode acessar as informações do usuário autenticado (ou identidade) na sua implementação MCP:

O segundo argumento do manipulador de ferramenta conterá o objeto authInfo, que inclui as informações do usuário autenticado:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// Inicialize com MCP Auth conforme mostrado nos exemplos anteriores
// ...

server.registerTool(
  'add',
  {
    description: 'Adiciona dois números',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // Agora você pode usar o objeto `authInfo` para acessar as informações autenticadas
  }
);

Próximos passos​

Continue lendo para ver um exemplo de ponta a ponta de como integrar o MCP Auth ao seu servidor MCP e como lidar com o fluxo de autenticação em clientes MCP.