Pular para o conteúdo principal

Configurar MCP Auth no servidor MCP

Com a última Especificação MCP (2025-06-18), seu servidor MCP atua como um Servidor de Recursos que valida tokens de acesso emitidos por servidores de autorização externos.

Para configurar o MCP Auth, você precisa de dois passos principais:

  1. Configurar os metadados do servidor de autorização - Defina quais servidores de autorização podem emitir tokens válidos para seu servidor MCP e oriente os clientes MCP sobre onde obter tokens de acesso
  2. Configurar os metadados do recurso protegido - Defina seu servidor MCP como um recurso protegido com escopos suportados

Passo 1: Configurar os metadados do servidor de autorização​

Busca automática de metadados​

A maneira mais fácil de configurar os metadados do servidor de autorização é usando as funções integradas que buscam os metadados a partir de URLs bem conhecidas. Se seu provedor estiver em conformidade com um dos seguintes padrões:

Você pode usar o fetchServerConfig para recuperar automaticamente os metadados fornecendo a URL do issuer:

import { fetchServerConfig } from 'mcp-auth';

// Buscar metadados do servidor de autorização
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // ou 'oauth'

Se seu emissor incluir um caminho, o comportamento difere um pouco entre OAuth 2.0 e OpenID Connect:

  • OAuth 2.0: A URL bem conhecida é anexada ao domínio do emissor. Por exemplo, se seu emissor for https://my-project.logto.app/oauth, a URL bem conhecida será https://auth.logto.io/.well-known/oauth-authorization-server/oauth.
  • OpenID Connect: A URL bem conhecida é anexada diretamente ao emissor. Por exemplo, se seu emissor for https://my-project.logto.app/oidc, a URL bem conhecida será https://auth.logto.io/oidc/.well-known/openid-configuration.

Descoberta sob demanda​

Se você estiver usando runtimes de borda como Cloudflare Workers, onde não é permitido buscar async no topo do escopo, você pode usar a descoberta sob demanda. Basta fornecer o issuer e o type, e os metadados serão buscados automaticamente quando necessário:

const authServerConfig = { issuer: '<issuer-url>', type: 'oidc' }; // ou 'oauth'

Outras formas de configurar os metadados do servidor de autorização​

Transpilação de dados personalizada​

Em alguns casos, os metadados retornados pelo provedor podem não estar no formato esperado. Se você tiver certeza de que o provedor está em conformidade, pode usar a opção transpileData para modificar os metadados antes de serem usados:

import { fetchServerConfig } from 'mcp-auth';

const authServerConfig = await fetchServerConfig('<auth-server-issuer>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Isso permite modificar o objeto de metadados antes de ser usado pelo MCP Auth. Por exemplo, você pode adicionar ou remover campos, alterar seus valores ou convertê-los para um formato diferente.

Buscar metadados de uma URL específica​

Se seu provedor tiver uma URL de metadados específica em vez das padrões, você pode usá-la de forma semelhante:

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', { type: 'oidc' }); // ou 'oauth'

Buscar metadados de uma URL específica com transpilação de dados personalizada​

Em alguns casos, a resposta do provedor pode estar malformada ou não estar em conformidade com o formato de metadados esperado. Se você tiver certeza de que o provedor está em conformidade, pode transpilar os metadados via a opção de configuração:

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Fornecer metadados manualmente​

Se seu provedor não suportar busca de metadados, você pode fornecer manualmente o objeto de metadados:

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // Os campos de metadados devem estar em camelCase
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... outros campos de metadados
  },
  type: 'oidc', // ou 'oauth'
};

Passo 2: Configurar os metadados do recurso protegido​

Após configurar os metadados do servidor de autorização, você precisa inicializar o MCPAuth como um Servidor de Recursos definindo os metadados dos seus recursos protegidos.

Este passo segue a especificação RFC 9728 (Metadados de Recurso Protegido OAuth 2.0) para descrever seu servidor MCP como um recurso protegido:

import { MCPAuth } from 'mcp-auth';

// Defina seu identificador de recurso
const resourceIdentifier = 'https://api.example.com/notes';

// Inicialize o MCPAuth no modo servidor de recursos
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig], // Usando a configuração do Passo 1
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Para múltiplos recursos, você pode fornecer um array de configurações de recursos protegidos, cada um com sua própria configuração de metadados.

A configuração mostrada acima cobre a configuração básica. Para parâmetros de metadados mais avançados, veja RFC 9728.

Passo 3: Montar o endpoint de metadados do recurso protegido​

Monte o roteador para servir o endpoint de metadados do recurso protegido. 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
import express from 'express';

const app = express();

const mcpAuth = new MCPAuth({/* ... */});

app.use(mcpAuth.protectedResourceMetadataRouter());