Autenticação MCP da Didit: iniciar sessão com OAuth

O MCP da Didit autentica-se com Iniciar sessão com a Didit (OAuth 2.1). Atua como um utilizador da Didit, com as permissões da função que tem na consola. Não existe modo de chave de API.

Iniciar sessão com a Didit

O servidor alojado (https://mcp.didit.me/mcp) é um servidor de recursos OAuth 2.1. A Didit Business Console (business.didit.me) é o servidor de autorização que aloja o ecrã de consentimento e emite os tokens. O seu cliente MCP executa o fluxo padrão automaticamente:

Descoberta

O cliente envia um pedido 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

Este documento indica o recurso (https://mcp.didit.me/mcp), o servidor de autorização (https://business.didit.me) e os âmbitos suportados. O mesmo documento também é disponibilizado na raiz do domínio, https://mcp.didit.me/.well-known/oauth-protected-resource, para os clientes que o procuram primeiro nesse endereço.

Registo (registo dinâmico de clientes)

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 identificador de cliente, regista-se no registration_endpoint (RFC 7591). Não tem de pré-configurar nada da sua parte: os clientes locais com um callback de loopback ou nativo (Claude Code, Cursor, MCP Inspector) e os clientes alojados na cloud com um callback revisto (Claude) registam-se desta forma. Um URL de retorno remoto que a Didit não tenha revisto é recusado com invalid_redirect_uri; esse cliente tem de ser registado primeiro por um operador.

Autorização (PKCE)

O cliente abre https://business.didit.me/authorize com um desafio PKCE S256. Você inicia sessão (ou regista-se) e vê exatamente que permissões são pedidas. Os clientes são públicos: o endpoint de token não aceita nenhum segredo de cliente (token_endpoint_auth_methods_supported é none), pelo que é o PKCE que associa o código ao cliente.

Consentimento

Você aprova. A consola emite uma sessão para essa aplicação, associada aos âmbitos que aprovou, e devolve um código de autorização, que o cliente troca no token_endpoint por um token de acesso e um token de atualização.

Chamar ferramentas

O cliente envia o token de acesso em todos os pedidos. O MCP valida-o com introspeção de token RFC 7662 no serviço de autenticação da Didit (os tokens são opacos, não JWT), lê as permissões da sua organização na resposta de introspeção e atua em seu nome durante esse pedido.

Âmbitos

Os metadados do recurso anunciam três âmbitos. O ecrã de consentimento mostra, em linguagem simples, os que um cliente pede:

Âmbito	Concede
`didit:management`	Gerir o 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 rever verificações: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` e `analytics`.
`didit:staff`	Reservado para contas de colaboradores da Didit. Não desbloqueia nada numa conta normal, e a versão de código aberto não define ferramentas exclusivas para colaboradores.

Ambos os âmbitos incluem analytics. Gerir lists requer didit:management; aceder a blocklist requer didit:verification. A referência das ferramentas indica o âmbito a que cada ferramenta pertence. Os âmbitos que aprova ficam associados ao token e são aplicados do lado do servidor, pelo que uma aplicação ligada apenas com didit:verification é recusada na área de gestão, mesmo que a sua própria função permitisse essa ação. O servidor de autorização também conhece os âmbitos OpenID (openid profile email); uma ligação que peça apenas esses pode saber quem você é e mais nada. As permissões efetivas de uma aplicação são a interseção dos âmbitos aprovados e da sua função na consola, nunca o mais amplo dos dois. Para criar uma sessão de verificação com didit_session_create, precisa do âmbito didit:verification e de uma função com create:sessions ou write:sessions. A função Programador inclui create:sessions. Aprovar apenas didit:management não permite criar sessões, mesmo que a sua função tenha a permissão necessária.

Funções e permissões

O token alojado representa você, pelo que o agente pode trabalhar em todas as organizações a que pertence numa única ligação. As ferramentas entre aplicações (didit_session_search, didit_analytics, didit_context_get e as restantes ferramentas *_search) agregam os resultados de todas elas automaticamente. A sua função é sempre imposta pelo backend da Didit, por organização. Cada ferramenta corresponde a uma cadeia de caracteres de permissão do backend (por exemplo, write:sessions para didit_session_update_status e delete:sessions para didit_session_delete); a referência das ferramentas indica a permissão de cada uma. O servidor também verifica essa permissão antes de enviar o pedido, com base nas permissões que a resposta de introspeção indica para a sua organização:

No modo enforce, uma ferramenta que a sua função não pode executar é excluída de tools/list, e uma chamada à mesma devolve um erro missing_scope que indica a permissão ("Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires.").
No modo shadow (o predefinido do servidor), todas as ferramentas são listadas e a chamada é enviada ao backend, que responde com 403 quando a função não tem a permissão; o veredicto é apenas registado no registo de auditoria do servidor.

Em qualquer dos casos, o MCP nunca concede mais do que a sua função na consola já permite. Um READER pode listar e ler; um OWNER ou ADMIN pode escrever e eliminar.

Duração do token

Uma aplicação aprovada recebe a sua própria sessão, separada da sessão do navegador a partir da qual a aprovou. Os tokens de acesso têm vida curta; o cliente renova-os silenciosamente com o token de atualização (grant_types_supported inclui refresh_token), e a renovação mantém os âmbitos da aplicação e continua associada a essa aplicação. Se uma renovação falhar (por exemplo, depois de desligar a aplicação), o cliente volta a executar Iniciar sessão com a Didit na chamada seguinte. Sair da consola não termina a sessão nas aplicações ligadas, e desligar uma aplicação nunca termina a sua sessão em lado nenhum.

Desligar uma aplicação

Na consola

Definições → Autenticação → Aplicações ligadas lista cada aplicação que aprovou, com o nome registado e as permissões que lhe foram concedidas. Desligar termina de imediato o acesso dessa aplicação: tanto o seu token de acesso como o seu token de atualização deixam de funcionar, e nada mais é afetado.

A partir da aplicação (RFC 7009)

Um cliente pode revogar o seu próprio acesso enviando o token para o revocation_endpoint do servidor de autorização, anunciado nos metadados em https://business.didit.me/.well-known/oauth-authorization-server. Tal como o RFC 7009 exige, uma chamada bem-sucedida responde com 200, quer o token ainda estivesse válido quer não, pelo que a resposta nunca indica se um token era válido. Um 503 significa que a revogação não pôde ser aplicada: trate o token como 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>"}'

Porque não há chave de API? Cada ferramenta MCP chama os endpoints da consola com âmbito de utilizador (/organization/{org}/application/{app}/…), que autorizam um token Bearer com privilégios por função e rejeitam x-api-key. Uma chave de API de aplicação destina-se a chamar a REST API diretamente a partir do seu próprio backend (por exemplo, criar sessões), e não a este MCP. didit_org_list_api_keys mostra os metadados das chaves com os valores ocultados; a ferramenta que revela uma chave em bruto fica oculta no conector alojado.

Ligar a partir de cada cliente

Todos os clientes seguem o mesmo fluxo; só muda a forma como lhes indica o URL.

Claude
Claude Code
Cursor
Cliente genérico

Use a ligação direta que a Business Console mostra na sua página de integração. 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 depois conclua Iniciar sessão com a Didit. O Claude Desktop usa o mesmo URL em Definições → Conectores → Add custom connector. Detalhes em Ligar o Claude.

claude mcp add --transport http didit https://mcp.didit.me/mcp

Em seguida, execute /mcp dentro do Claude Code para iniciar sessão no navegador.

~/.cursor/mcp.json:

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

O Cursor regista-se a si próprio e abre o navegador na primeira utilização.

Configure qualquer cliente Streamable HTTP com suporte a OAuth 2.1 para https://mcp.didit.me/mcp. Deve:

Fazer POST /mcp, receber 401 e ler resource_metadata a partir de WWW-Authenticate.
Obter 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.
Registar-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 cada POST /mcp.

Os clientes sem suporte a OAuth podem funcionar através de npx -y mcp-remote@latest https://mcp.didit.me/mcp, que executa os passos 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 de /mcp significa que o token está em falta, expirou ou foi revogado: o cliente deve renovar o token ou repetir Iniciar sessão com a Didit. Um 403 ou um erro missing_scope numa ferramenta específica significa normalmente que a sua função não tem essa permissão (por exemplo, um READER a tentar uma escrita) ou que a ligação foi aprovada sem o âmbito que essa ferramenta exige, e não que toda a ligação esteja avariada. Voltar a ligar e aprovar ambos os âmbitos resolve o segundo caso; o primeiro exige uma alteração de função. Se todas as ferramentas falharem, verifique Definições → Autenticação → Aplicações ligadas na consola: uma aplicação que foi desligada aí tem de ser aprovada novamente.

Referência de ferramentas

O que faz cada ferramenta, o seu âmbito e a permissão da sua função.

Avançado

Funções, comportamento entre aplicações e alojamento próprio.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

Autenticação MCP da Didit: iniciar sessão com OAuth

Iniciar sessão com a Didit

Âmbitos

Funções e permissões

Duração do token

Desligar uma aplicação

Ligar a partir de cada cliente

Falhas de autenticação

Referência de ferramentas

Avançado

​Iniciar sessão com a Didit

​Âmbitos

​Funções e permissões

​Duração do token

​Desligar uma aplicação

​Ligar a partir de cada cliente

​Falhas de autenticação

Referência de ferramentas

Avançado

Iniciar sessão com a Didit

Âmbitos

Funções e permissões

Duração do token

Desligar uma aplicação

Ligar a partir de cada cliente

Falhas de autenticação