> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação do MCP da Didit: login com Didit (OAuth)

> O MCP da Didit usa OAuth 2.1 com PKCE, registro dinâmico de clientes, metadados de recurso, escopos e funções. Saiba conectar cada cliente.

O Didit MCP é autenticado com **Entrar com a Didit** (OAuth 2.1). Ele atua como um **usuário** da Didit com as permissões da sua função no console. **Não existe modo de chave de API.**

***

## Entrar com a Didit

O servidor hospedado (`https://mcp.didit.me/mcp`) é um **servidor de recursos** OAuth 2.1. O **Didit Business Console** (`business.didit.me`) é o **servidor de autorização**: ele hospeda a tela de consentimento e emite os tokens. Seu cliente MCP conduz o fluxo padrão automaticamente:

**1. Descoberta**

O cliente envia uma requisição POST para `/mcp` sem token e recebe `401` com um cabeçalho `WWW-Authenticate: Bearer`, cujo `resource_metadata` aponta para os metadados do recurso protegido (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Esse documento informa o recurso (`https://mcp.didit.me/mcp`), o servidor de autorização (`https://business.didit.me`) e os escopos suportados. O mesmo documento também é servido na raiz da origem, `https://mcp.didit.me/.well-known/oauth-protected-resource`, para clientes que consultam esse endereço primeiro.

**2. Registro (registro dinâmico de cliente)**

O cliente lê os metadados do servidor de autorização em `https://business.didit.me/.well-known/oauth-authorization-server` e, se ainda não tiver um client id, registra-se no `registration_endpoint` (RFC 7591). Não há nada a provisionar previamente do seu lado: clientes locais com callback de loopback ou nativo (Claude Code, Cursor, MCP Inspector) e clientes hospedados na nuvem com callback revisado (Claude) se registram dessa forma. Uma URL de retorno remota que a Didit não revisou é recusada com `invalid_redirect_uri`; nesse caso, um operador precisa registrar o cliente antes.

**3. Autorização (PKCE)**

O cliente abre `https://business.didit.me/authorize` com um desafio PKCE S256. Você entra (ou se cadastra) e vê exatamente quais permissões estão sendo solicitadas. Os clientes são públicos: o endpoint de token não aceita client secret (`token_endpoint_auth_methods_supported` é `none`), então é o PKCE que vincula o código ao cliente.

**4. Consentimento**

Você aprova. O console cria uma sessão para esse app, vinculada aos escopos que você aprovou, e retorna um código de autorização, que o cliente troca no `token_endpoint` por um access token e um refresh token.

**5. Chamada de ferramentas**

O cliente envia o access token em cada requisição. O MCP o valida por introspecção de token RFC 7662 no serviço de autenticação da Didit (os tokens são opacos, não JWTs), lê as permissões da sua organização na resposta da introspecção e age como **você** durante essa requisição.

### Escopos

Os metadados do recurso anunciam três escopos. A tela de consentimento mostra, em linguagem simples, os que um cliente solicita:

| Escopo | Concede |
| - | - |
| `didit:management` | Gerenciar seu espaço de trabalho — `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` e `analytics`. |
| `didit:verification` | Executar e revisar verificações — `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` e `analytics`. |
| `didit:staff` | Reservado para contas da equipe da Didit. Não libera nada para uma conta comum, e a versão open source não define ferramentas exclusivas da equipe. |

Os dois escopos incluem `analytics`. Gerenciar `lists` exige `didit:management`; acessar `blocklist` exige `didit:verification`.

A [referência de ferramentas](https://docs.didit.me/pt-br/integration/mcp/tools.md) lista o escopo de cada ferramenta. Os escopos que você aprova ficam no token e são aplicados no servidor, então um app conectado apenas com `didit:verification` tem as operações de gerenciamento recusadas, mesmo que sua própria função permitisse. O servidor de autorização também reconhece os escopos OpenID (`openid profile email`); uma conexão que solicita apenas esses escopos consegue saber quem você é e nada mais.

As permissões efetivas de um app são a **interseção** dos escopos aprovados com a sua função no console — nunca o mais amplo dos dois.

Para criar uma sessão de verificação com `didit_session_create`, você precisa do escopo `didit:verification` **e** de uma função com `create:sessions` ou `write:sessions`. A função **Desenvolvedor** inclui `create:sessions`. Aprovar apenas `didit:management` não permite criar sessões, mesmo que sua função tenha a permissão necessária.

### Funções e permissões

O token hospedado representa **você**, então o agente pode trabalhar em **todas as organizações das quais você faz parte** com uma única conexão — as ferramentas que abrangem vários apps (`didit_session_search`, `didit_analytics`, `didit_context_get` e as demais ferramentas `*_search`) agregam os dados de todas elas automaticamente.

O backend da Didit sempre aplica as permissões da sua **função**, por organização. Cada ferramenta corresponde a uma string de permissão do backend (por exemplo, `write:sessions` para `didit_session_update_status` e `delete:sessions` para `didit_session_delete`); a [referência de ferramentas](https://docs.didit.me/pt-br/integration/mcp/tools.md) mostra essa permissão para cada ferramenta. O servidor também verifica essa permissão antes de enviar a requisição, usando as permissões que a resposta da introspecção traz para a sua organização:

* No modo `enforce`, uma ferramenta que sua função não pode executar fica fora de `tools/list`, e chamá-la mesmo assim retorna um erro `missing_scope` que informa a permissão (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* No modo `shadow` (o padrão do servidor), todas as ferramentas são listadas e a chamada segue até o backend, que responde `403` quando a função não tem a permissão; o resultado da verificação é apenas registrado no registro de auditoria do servidor.

Em qualquer caso, o MCP nunca concede mais do que sua função no console já permite. Um `READER` pode listar e ler; um `OWNER` ou `ADMIN` pode gravar e excluir.

### Validade do token

Um app aprovado recebe uma sessão própria, separada da sessão do navegador a partir da qual você o aprovou. Os access tokens têm vida curta; o cliente os renova silenciosamente com o refresh token (`grant_types_supported` inclui `refresh_token`), e a renovação mantém os escopos do app e continua vinculada a esse app. Se uma renovação falhar (por exemplo, depois que você desconectar o app), o cliente executa **Entrar com a Didit** novamente na próxima chamada.

Sair do console não encerra as sessões dos apps conectados, e desconectar um app nunca encerra sua sessão em lugar nenhum.

### Desconectar um app

**1. Pelo console**

**Settings → Authentication → Connected apps** lista todos os apps que você aprovou, com o nome registrado e as permissões concedidas a cada um. **Desconectar** encerra imediatamente o acesso desse app: tanto o access token quanto o refresh token deixam de funcionar, e nada mais é afetado.

**2. Pelo app (RFC 7009)**

Um cliente pode revogar o próprio acesso enviando o token por POST para o `revocation_endpoint` do servidor de autorização, anunciado nos metadados em `https://business.didit.me/.well-known/oauth-authorization-server`. Como exige a RFC 7009, uma chamada bem-sucedida responde `200` quer o token ainda estivesse ativo, quer não, então a resposta nunca informa se um token era válido. Um `503` significa que a revogação não pôde ser aplicada: considere o token ainda válido e tente novamente.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **Por que não uma chave de API?** Toda ferramenta MCP chama os endpoints do console vinculados ao usuário (`/organization/{org}/application/{app}/…`), que autorizam um Bearer token com privilégios por função e **rejeitam `x-api-key`**. A chave de API de uma aplicação serve para chamar a [API REST](https://docs.didit.me/openapi-25.json) diretamente do seu próprio backend (por exemplo, para criar sessões), e não para este MCP. `didit_org_list_api_keys` mostra os metadados das chaves com os valores ocultados; a ferramenta que revela uma chave em texto puro fica oculta no conector hospedado.

***

## Conexão em cada cliente

Todos os clientes executam o mesmo fluxo; só muda a forma como você informa a URL.

> [tab] Claude
>
> Use o deep link que o Business Console mostra na página de integração. Ele abre o claude.ai com a caixa de diálogo **Add custom connector** já preenchida:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Confirme e conclua o **Log in with Didit**. O Claude Desktop usa a mesma URL em **Settings → Connectors → Add custom connector**. Mais detalhes em [Conectar o Claude](https://docs.didit.me/pt-br/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Em seguida, execute `/mcp` dentro do Claude Code para iniciar o login pelo navegador.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> O Cursor se registra automaticamente e abre o navegador no primeiro uso.

> [tab] Cliente genérico
>
> Aponte qualquer cliente Streamable HTTP com suporte a OAuth 2.1 para `https://mcp.didit.me/mcp`. Ele deve:
>
> 1. Fazer `POST /mcp`, receber `401` e ler `resource_metadata` em `WWW-Authenticate`.
> 2. Buscar `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` e, depois, os metadados do servidor de autorização em `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Registrar-se no `registration_endpoint` se não tiver um ID de cliente.
> 4. Executar o fluxo de código de autorização com PKCE (S256) no `authorization_endpoint` e trocar o código no `token_endpoint`.
> 5. Enviar `Authorization: Bearer <access_token>` em todo `POST /mcp`.
>
> Clientes sem suporte a OAuth podem usar `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, que executa as etapas 1 a 5 por eles.

***

## Falhas de autenticação

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

Um `401` vindo de `/mcp` significa que o token está ausente, expirado ou foi revogado: o cliente deve renovar o token ou executar novamente **Entrar com a Didit**.

Um `403` ou um erro `missing_scope` em uma ferramenta *específica* geralmente significa que a sua **função** não tem essa permissão (por exemplo, um `READER` tentando realizar uma operação de escrita) ou que a conexão foi aprovada **sem o escopo** de que essa ferramenta precisa, e não que a conexão inteira esteja com problema. Reconectar e aprovar os dois escopos resolve o segundo caso; o primeiro exige uma mudança de função.

Se todas as ferramentas falharem, verifique **Settings → Authentication → Connected apps** no console: um app que foi desconectado ali precisa ser aprovado novamente.

***

> [card] [Referência de ferramentas](https://docs.didit.me/pt-br/integration/mcp/tools.md)
>
> O que cada ferramenta faz, seu escopo e a permissão de função exigida.

> [card] [Avançado](https://docs.didit.me/pt-br/integration/mcp/advanced.md)
>
> Funções, comportamento entre aplicações e auto-hospedagem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.