Como configurar o OAuth 2.0 no MCP Server Trigger

Saiba como habilitar e configurar a autorização OAuth 2.0 no MCP Server Trigger na Digibee Integration Platform.

O MCP Server Trigger suporta o fluxo de autorização definido pelo OAuth 2.1, com PKCE (Proof Key for Code Exchange), o padrão recomendado para servidores MCP com transporte HTTP. Com OAuth, antes de acessar qualquer recurso, o cliente precisa comprovar que o usuário autorizou o acesso, por meio de um token emitido por um servidor de autorização confiável.

A autorização OAuth é recomendada quando o seu servidor MCP acessa dados de usuários, realiza ações administrativas ou opera em ambientes corporativos com controles de acesso rigorosos.

Antes de começar

Antes de configurar o OAuth 2.0 no MCP Server Trigger, verifique se você tem:

• Um servidor de autorização compatível com OAuth 2.1 já configurado (por exemplo, Auth0, Azure AD ou Okta)

• A URL de metadados ou o endpoint de discovery do servidor de autorização

• Os escopos que suas ferramentas vão exigir, definidos no seu servidor de autorização

Como funciona o fluxo OAuth 2.0

O OAuth 2.0 protege seu pipeline exigindo que todo cliente comprove que foi autorizado antes de acessar qualquer ferramenta. Sem um token válido, o MCP Server Trigger rejeita a requisição. O fluxo abaixo descreve como um cliente obtém e usa esse token.

1. Um cliente MCP envia uma requisição ao pipeline sem um access token.

2. O MCP Server Trigger responde com HTTP 401 Unauthorized, incluindo um header que aponta para o documento Protected Resource Metadata.

3. O cliente busca o documento de metadados e descobre a localização do servidor de autorização.

4. O cliente conclui o fluxo de autorização OAuth 2.1 com o servidor de autorização e obtém um access token.

5. O cliente reenvia a requisição, desta vez incluindo o access token no header Authorization: Bearer <token>.

6. O MCP Server Trigger valida o token e, se válido, processa a requisição.

Toda requisição HTTP do cliente para o servidor deve incluir o header Authorization, mesmo que as requisições façam parte da mesma sessão.

Passo a passo

1

Configure seu servidor de autorização

Seu servidor de autorização deve expor os endpoints de metadados OAuth 2.0 que o cliente MCP usará para discovery. Ele deve fornecer:

• OAuth 2.0 Authorization Server Metadata em /.well-known/oauth-authorization-server

• OpenID Connect Discovery em /.well-known/openid-configuration

Além disso, o servidor de autorização deve:

• Suportar PKCE (Proof Key for Code Exchange) com o método de desafio S256

• Incluir code_challenge_methods_supported na resposta de metadados

• Suportar o parâmetro resource (Resource Indicators for OAuth 2.0, definido na RFC 8707)

• Emitir access tokens de curta duração para reduzir o impacto de vazamento de tokens

O parâmetro resource vincula o token ao endpoint específico do seu MCP Server Trigger, por exemplo https://your-pipeline.digibee.io/mcp. Isso impede que tokens emitidos para o seu pipeline sejam reutilizados em outros serviços.

Exemplo de metadados do servidor de autorização (formato OAuth 2.0 Authorization Server Metadata)

{
  "issuer": "https://your-auth-server.example.com",
  "authorization_endpoint": "https://your-auth-server.example.com/authorize",
  "token_endpoint": "https://your-auth-server.example.com/token",
  "jwks_uri": "https://your-auth-server.example.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["read:customers", "write:orders", "read:reports"],
  "client_id_metadata_document_supported": true
}

2

Registre seu cliente MCP

Os clientes MCP precisam ser registrados no seu servidor de autorização antes de obter tokens. A Digibee suporta três abordagens de registro:

Client ID Metadata Documents

O cliente usa uma URL HTTPS como client_id. Essa URL deve apontar para um documento JSON com os metadados do cliente. Esta é a abordagem recomendada para clientes sem relação prévia com o servidor de autorização.

Requisitos para o documento de metadados:

• Hospedado em uma URL HTTPS

• Contém client_id, client_name e redirect_uris

• O valor de client_id deve corresponder exatamente à URL do documento

Exemplo de documento de metadados:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Seu servidor de autorização deve incluir "client_id_metadata_document_supported": true nos seus metadados para indicar suporte a essa abordagem.

Pré-registro

O cliente e o servidor têm uma relação prévia. O cliente usa um client_id estático (e, quando aplicável, credenciais estáticas) obtido por meio de um processo de registro anterior, por exemplo por uma interface de configuração fornecida pelo seu servidor de autorização.

Registro dinâmico de cliente

O cliente se registra de forma programática no endpoint de registro do servidor de autorização usando o OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591). Esta abordagem está incluída por compatibilidade com versões anteriores.

POST /register HTTP/1.1
Host: your-auth-server.example.com
Content-Type: application/json

{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"]
}

3

Habilite o OAuth 2.0 no trigger

1. Abra o pipeline que contém o MCP Server Trigger e clique no trigger.

2. Habilite o toggle OAuth2 JWT.

3. No campo OAuth2 Authorization Server, insira a URL do seu servidor de autorização (por exemplo, https://your-auth-server.example.com).

4. Clique em Salvar.

Após salvar, teste a configuração enviando uma requisição não autenticada para o endpoint do trigger. Você deve receber uma resposta 401 com o header WWW-Authenticate contendo a URL resource_metadata.

4

Configure ferramentas com escopos

Com o OAuth 2.0 habilitado, defina os escopos que cada ferramenta exige. Os escopos são incorporados ao token JWT quando um agente invoca uma ferramenta e permitem a aplicação de permissões granulares como parte do fluxo do trigger.

1. Abra a configuração do MCP Server Trigger.

2. Na seção MCP Server Tools, clique na ferramenta que deseja configurar (ou clique em Adicionar Ferramenta para criar uma nova).

3. No campo Escopos, digite o escopo e pressione Enter ou Tab para adicioná-lo como tag.

4. Repita o processo para cada escopo que a ferramenta exige.

5. Clique em Salvar.

Exemplos de escopos:

Ferramenta	Escopos
search_customer	read:customers
update_order	read:orders, write:orders
generate_report	read:reports

Pipelines criados antes da release de 27 de janeiro de 2026 que utilizam o MCP Server Trigger devem ser reconfigurados devido à inclusão de Escopos. Abra a configuração do trigger e clique em Salvar novamente. Por segurança, recomendamos gerar uma cópia de seus Block Executions antes de realizar esta atualização.

Conectando clientes MCP

Os clientes a seguir foram validados para funcionar com o fluxo OAuth 2.0 do MCP Server Trigger.

Claude Desktop

1. Abra o arquivo de configuração do Claude Desktop (claude_desktop_config.json).

2. Adicione a entrada do servidor MCP com a URL do seu pipeline como endpoint:

{
  "mcpServers": {
    "my-digibee-pipeline": {
      "url": "https://your-pipeline.digibee.io/mcp",
      "authorizationUrl": "https://your-auth-server.example.com"
    }
  }
}

1. Reinicie o Claude Desktop. Na próxima tentativa de conexão, ele iniciará o fluxo OAuth 2.0 e abrirá uma janela do navegador para autenticação.

Cursor

1. Acesse Settings > MCP Servers no Cursor.

2. Adicione um novo servidor com o endpoint do seu pipeline e a URL do servidor de autorização.

3. O Cursor executará o fluxo OAuth 2.0 automaticamente na primeira conexão.

OpenAI Agent Builder

1. Na configuração do seu agente, adicione a URL do servidor MCP apontando para o seu pipeline na Digibee.

2. Defina o método de autenticação como OAuth 2.0 e forneça a URL de metadados do servidor de autorização.

3. O Agent Builder buscará os metadados do servidor e concluirá o fluxo de autorização antes de realizar chamadas de ferramentas.

Validação de token e tratamento de erros

O MCP Server Trigger valida todo access token recebido antes de processar a requisição. A validação inclui:

• Verificação da assinatura do token com as chaves públicas do servidor de autorização

• Confirmação de que o audience do token corresponde à URI canônica do MCP Server Trigger

• Confirmação de que o token não expirou

Se a validação falhar, o trigger retorna o erro HTTP correspondente:

Código de status	Descrição	Quando ocorre
401 Unauthorized	Token ausente, expirado ou inválido	Nenhum token enviado ou token reprovado na validação
403 Forbidden	Permissões insuficientes	Token válido, mas sem os escopos exigidos pela ferramenta
400 Bad Request	Requisição malformada	Requisição de autorização incorretamente formada

Tratamento de erros de escopo insuficiente

Se um cliente MCP enviar um token válido, mas o token não incluir os escopos exigidos pela ferramenta chamada, o pipeline retorna um erro JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": "2",
  "error": {
    "code": -32001,
    "message": "Permission denied. Token does not have the required scope for this tool."
  }
}

Os clientes MCP devem responder a este erro iniciando um fluxo de autorização step-up: solicitando um novo token que inclua os escopos adicionais e, em seguida, reenviando a requisição original.

Os clientes MCP devem implementar limites de tentativas para fluxos de autorização step-up. Falhas repetidas para o mesmo recurso e combinação de escopos devem ser tratadas como falha permanente de autorização e comunicadas ao usuário.

Boas práticas de segurança

Ao implantar o OAuth 2.0 com o MCP Server Trigger, siga estas práticas:

• Use HTTPS em todos os lugares. Todos os endpoints do servidor de autorização e URIs de redirecionamento devem usar HTTPS. A única exceção são URIs de localhost usadas durante o desenvolvimento local.

• Valide o audience do token. O trigger valida que os access tokens foram emitidos especificamente para a URI canônica do seu pipeline. Não reutilize tokens em diferentes serviços.

• Não repasse tokens. Se o seu pipeline chamar APIs externas, obtenha um token separado para cada serviço. Nunca encaminhe o token recebido do cliente MCP.

• Use tokens de curta duração. Configure seu servidor de autorização para emitir access tokens de curta duração. Para clientes públicos, habilite a rotação de refresh tokens.

• Aplique o princípio do menor privilégio. Defina escopos no nível da ferramenta e solicite apenas os escopos que cada ferramenta realmente precisa.

Próximos passos

Agora que o seu MCP Server Trigger está protegido com OAuth 2.0, leia MCP Server Trigger para consultar a referência completa de configuração do trigger, incluindo a configuração de schemas de ferramentas e templates de payload para testes.