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

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:

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):

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.

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.

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.

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.

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

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.

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.

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>"}'

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 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.

Claude
Claude Code
Cursor
Cliente genérico

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:

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.

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.

~/.cursor/mcp.json:

{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }

O Cursor se registra automaticamente e abre o navegador no primeiro uso.

Aponte qualquer cliente Streamable HTTP com suporte a OAuth 2.1 para https://mcp.didit.me/mcp. Ele deve:

Fazer POST /mcp, receber 401 e ler resource_metadata em WWW-Authenticate.
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.
Registrar-se no registration_endpoint se não tiver um ID de cliente.
Executar o fluxo de código de autorização com PKCE (S256) no authorization_endpoint e trocar o código no token_endpoint.
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

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.

Referência de ferramentas

O que cada ferramenta faz, seu escopo e a permissão de função exigida.

Avançado

Funções, comportamento entre aplicações e auto-hospedagem.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

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

Entrar com a Didit

Escopos

Funções e permissões

Validade do token

Desconectar um app

Conexão em cada cliente

Falhas de autenticação

Referência de ferramentas

Avançado

​Entrar com a Didit

​Escopos

​Funções e permissões

​Validade do token

​Desconectar um app

​Conexão em cada cliente

​Falhas de autenticação

Referência de ferramentas

Avançado

Entrar com a Didit

Escopos

Funções e permissões

Validade do token

Desconectar um app

Conexão em cada cliente

Falhas de autenticação