Configurar autenticação Bearer no servidor MCP

O MCP Auth oferece várias formas de configurar a autorização Bearer em seu servidor MCP:

• Modo JWT (JSON Web Token): Um método de autorização integrado que verifica JWTs com afirmações de reivindicações (claims).
• Modo personalizado: Permite implementar sua própria lógica de autorização.

Configurar autenticação Bearer com modo JWT

Se o seu provedor OAuth / OIDC emitir JWTs para autorização, você pode usar o modo JWT integrado no MCP Auth. Ele verifica a assinatura do JWT, expiração e outras reivindicações que você especificar; em seguida, preenche as informações de autenticação no contexto da requisição para processamento posterior na sua implementação MCP.

Validação de escopo (Scope)

Aqui está um exemplo de validação básica de escopo:

Python

from mcpauth import MCPAuth
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyMCPServer")
mcp_auth = MCPAuth(
    # Inicialize com a configuração do seu servidor de autenticação
)
bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) 

app = Starlette(
    routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])]
)

Node.js

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  /* ... */
});
const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); 

app.use('/mcp', bearerAuth, (req, res) => {
  // Agora `req.auth` contém as informações de autenticação
  console.log(req.auth);
});

No exemplo acima, especificamos que o JWT requer os escopos read e write. Se o JWT não contiver nenhum desses escopos, a requisição será rejeitada com um erro 403 Forbidden.

Validação de indicador de recurso (Resource indicator) (RFC 8707)

Se o seu provedor for baseado em OIDC, ou suportar a extensão Resource Indicator, você também pode especificar a opção audience para validar a reivindicação aud (público) no JWT. Isso é útil para garantir que o JWT seja destinado ao seu servidor MCP.

Verifique a documentação do seu provedor para saber se ele suporta a extensão Resource Indicator e como configurá-la. Alguns provedores podem usar outros termos como "audience", "API resource" ou "API indicator" para se referir ao mesmo conceito.

Uma vez que o indicador de recurso esteja configurado, você pode especificá-lo no middleware bearerAuth:

Python

bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt",
    audience="https://api.example.com/mcp",  # O público esperado para o JWT
    required_scopes=["read", "write"]
)

Node.js

const bearerAuth = mcpAuth.bearerAuth('jwt', {
  audience: 'https://api.example.com/mcp', // O público esperado para o JWT
  requiredScopes: ['read', 'write'],
});

No exemplo acima, o MCP Auth irá validar tanto a reivindicação aud no JWT quanto os escopos necessários.

Fornecer opções personalizadas para a verificação do JWT

Você também pode fornecer opções personalizadas para a biblioteca de verificação de JWT subjacente:

Python

No SDK Python, usamos PyJWT para verificação de JWT. Você pode usar as seguintes opções:

• leeway: Permite uma certa margem ao verificar o tempo de expiração do JWT (em segundos). O padrão é 60 segundos.

bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt",
    audience="https://api.example.com/mcp",
    required_scopes=["read", "write"]
    leeway=10,  # Reduz a diferença de relógio permitindo 10 segundos de margem
)

Node.js

No SDK Node.js, usamos a biblioteca jose para verificação de JWT. Você pode fornecer as seguintes opções:

• jwtVerify: Opções para o processo de verificação do JWT (função jwtVerify do jose).
• remoteJwtSet: Opções para buscar o conjunto remoto de JWT (createRemoteJWKSet do jose).

const bearerAuth = mcpAuth.bearerAuth('jwt', {
  audience: 'https://api.example.com/mcp',
  requiredScopes: ['read', 'write'],
  jwtVerify: {
    clockTolerance: 60, // Permite uma diferença de relógio de 60 segundos
  },
  remoteJwtSet: {
    timeoutDuration: 10 * 1000, // Timeout de 10 segundos para buscar o conjunto remoto de JWT
  },
});

Configurar autenticação Bearer com verificação personalizada

Se o seu provedor OAuth / OIDC não emitir JWTs, ou se você quiser implementar sua própria lógica de autorização, o MCP Auth permite criar uma função de verificação personalizada:

info

Como o middleware Bearer auth irá verificar o emissor (iss), público (aud) e escopos necessários (scope) com o resultado da verificação fornecido, não há necessidade de implementar essas verificações em sua função de verificação personalizada. Você pode focar em verificar a validade do token (por exemplo, assinatura, expiração, etc.) e retornar o objeto de informações de autenticação.

Python

from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode
from mcpauth.types import AuthInfo

async def custom_verification(token: str) -> AuthInfo:
    # Implemente sua lógica personalizada de verificação aqui
    info = await verify_token(token)
    if not info:
        raise MCPAuthJwtVerificationException(
            MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED
        )
    return info  # Retorne o objeto de informações de autenticação

bearer_auth = mcp_auth.bearer_auth_middleware(
    custom_verification,
    required_scopes=["read", "write"]
)

Node.js

const bearerAuth = mcpAuth.bearerAuth(
  async (token) => {
    // Implemente sua lógica personalizada de verificação aqui
    const info = await verifyToken(token);
    if (!info) {
      throw new MCPAuthJwtVerificationError('jwt_verification_failed');
    }
    return info; // Retorne o objeto de informações de autenticação
  },
  { requiredScopes: ['read', 'write'] }
);

Aplicar autenticação Bearer no seu servidor MCP

Para proteger seu servidor MCP com autenticação Bearer, você precisa aplicar o middleware Bearer auth à instância do seu servidor MCP.

Python

bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"])
app = Starlette(
    routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])]
)

Node.js

const app = express();
app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

Isso garantirá que todas as requisições recebidas sejam autenticadas e autorizadas de acordo com as configurações de autenticação Bearer, e as informações de autenticação estarão disponíveis no contexto da requisição.

Você pode então acessar as informações na implementação do seu servidor MCP:

Python

@mcp.tool()
async def whoami() -> dict:
    # `mcp_auth.auth_info` é o objeto de contexto para a requisição atual
    auth_info = mcp_auth.auth_info
    print(f"Usuário autenticado: {auth_info.subject}")
    return {"subject": auth_info.subject}

Node.js

// `authInfo` será carregado a partir do objeto `req.auth`
server.tool('whoami', ({ authInfo }) => {
  console.log(`Usuário autenticado: ${authInfo.subject}`);
  return { subject: authInfo.subject };
});