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:

• OAuth 2.0 Authorization Server Metadata
• OpenID Connect Discovery

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

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

# Buscar metadados do servidor de autorização
auth_server_config = fetch_server_config(
    "https://auth.logto.io/oidc",
    AuthServerType.OIDC  # ou AuthServerType.OAUTH
)

Node.js

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 o seu issuer 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 issuer. Por exemplo, se seu issuer 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 issuer. Por exemplo, se seu issuer for https://my-project.logto.app/oidc, a URL bem conhecida será https://auth.logto.io/oidc/.well-known/openid-configuration.

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 transpile_data para modificar os metadados antes de serem utilizados:

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_server_config = fetch_server_config(
    '<auth-server-url>',
    type=AuthServerType.OIDC,
    transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
)

Node.js

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 utilizado 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 possui uma URL de metadados específica em vez das padrões, você pode usá-la de forma semelhante:

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config_by_well_known_url

auth_server_config = fetch_server_config_by_well_known_url(
    '<metadata-url>',
    type=AuthServerType.OIDC # ou AuthServerType.OAUTH
)

Node.js

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 opção de configuração:

Python

from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url

auth_server_config = fetch_server_config_by_well_known_url(
    '<metadata-url>',
    type=AuthServerType.OIDC,
    transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
)

Node.js

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

Fornecer metadados manualmente

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

Python

from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata

auth_server_config = AuthServerConfig(
    type=AuthServerType.OIDC,  # ou AuthServerType.OAUTH
    metadata=AuthorizationServerMetadata(
        issuer='<issuer-url>',
        authorization_endpoint='<authorization-endpoint-url>',
        # ... outros campos de metadados
    ),
)

Node.js

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 (OAuth 2.0 Protected Resource Metadata) para descrever seu servidor MCP como um recurso protegido:

Python

from mcpauth import MCPAuth
from mcpauth.config import ResourceServerConfig, ResourceServerMetadata

# Defina seu identificador de recurso
resource_id = "https://api.example.com/notes"

# Inicialize o MCPAuth no modo servidor de recursos
mcp_auth = MCPAuth(
    protected_resources=ResourceServerConfig(
        metadata=ResourceServerMetadata(
            resource=resource_id,
            authorization_servers=[auth_server_config],  # Usando a configuração do Passo 1
            scopes_supported=[
                "read:notes",
                "write:notes",
            ],
        )
    )
)

Node.js

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 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, consulte 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

Python

from starlette.applications import Starlette
from mcpauth import MCPAuth

mcp_auth = MCPAuth({/* ... */})

app = Starlette(routes=[
    *mcp_auth.resource_metadata_router().routes,
])

Node.js

import express from 'express';

const app = express();

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

app.use(mcpAuth.protectedResourceMetadataRouter());