> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/mcp-server/how-to-configure-oauth-2.0-on-the-mcp-server-trigger.md). # Como configurar o OAuth 2.0 no MCP Server Trigger 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 `. 6. O MCP Server Trigger valida o token e, se válido, processa a requisição. {% hint style="info" %} 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. {% endhint %} ## **Passo a passo** {% stepper %} {% step %} ### **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](https://www.rfc-editor.org/rfc/rfc8707.html)) * 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)** ```json { "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 } ``` {% endstep %} {% step %} ### **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:** ```json { "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)](https://datatracker.ietf.org/doc/html/rfc7591). Esta abordagem está incluída por compatibilidade com versões anteriores. ```json 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"] } ``` {% endstep %} {% step %} ### **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`. {% endstep %} {% step %} ### **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` | {% hint style="warning" %} 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. {% endhint %} {% endstep %} {% endstepper %} ## **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: ```json { "mcpServers": { "my-digibee-pipeline": { "url": "https://your-pipeline.digibee.io/mcp", "authorizationUrl": "https://your-auth-server.example.com" } } } ``` 3. 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: ```json { "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. {% hint style="warning" %} 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. {% endhint %} ## **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](/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/mcp-server.md) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/mcp-server/how-to-configure-oauth-2.0-on-the-mcp-server-trigger.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.