Saltar para o conteúdo principal

​
Âmbitos e permissões por função

O conector funciona com os âmbitos didit:management e didit:verification (um terceiro, didit:staff, é anunciado, mas só é relevante para contas da equipa da Didit). Ambos os limites são aplicados em cada chamada: o token contém os âmbitos que aprovou e, dentro desses âmbitos, a sua função na consola decide o que pode fazer. O acesso efetivo é a interseção, por isso aprovar apenas didit:verification mantém a superfície de gestão fechada, mesmo para um OWNER. Cada ferramenta corresponde a uma permissão do backend (read:sessions, write:workflows, delete:lists, e assim por diante; a referência de ferramentas indica a permissão de cada uma). O servidor verifica previamente essa permissão com base nas permissões da organização devolvidas pela introspeção do token; o comportamento dessa verificação é controlado por MCP_PERMISSION_MODE: O MCP nunca eleva os seus privilégios para além da sua função. Um 403 numa ferramenta significa que a sua função não tem essa permissão, e não que toda a ligação falhou.

​
Resolução entre aplicações e organizações

A API de gestão da Didit tem âmbito por aplicação (/organization/{org}/application/{app}/…). O MCP resolve o âmbito por si:
  • Uma única organização + aplicação → resolvido automaticamente; nunca precisa de passar IDs.
  • Várias aplicações → as ferramentas entre aplicações (didit_session_search, didit_transaction_search, didit_case_search, didit_vendor_user_search, didit_vendor_business_search, didit_workflow_search, didit_analytics) agregam os dados de todas numa só chamada, com cada linha marcada com o seu organization_id / application_id.
  • As ferramentas de listagem por aplicação (didit_session_list, didit_transaction_list, didit_case_list, didit_vendor_user_list, didit_vendor_business_list, didit_workflow_list) abrangem automaticamente todas as aplicações quando não especifica uma, por isso um simples «listar as minhas sessões» funciona mesmo com muitas aplicações. Passe organization_id + application_id para restringir a uma única aplicação.
Use didit_context_get para ver todas as suas organizações e aplicações (e os respetivos IDs) numa única chamada. A ferramenta também indica o mode de cada aplicação (live ou sandbox), por isso nunca adivinhe o ambiente a partir do nome de uma aplicação. didit_session_create aceita um sandbox_scenario nas aplicações sandbox para execuções de teste sem faturação.

​
O que contém o catálogo alojado

O conector alojado disponibiliza 169 ferramentas. Lista também 17 ferramentas do Investigator, que só funcionam depois de o Investigator estar ativado para a sua organização. Duas outras ferramentas, didit_org_top_up (processo de pagamento da Stripe) e didit_org_reveal_application_api_key (segredo em bruto), ficam ocultas do tools/list de todos os chamadores autenticados por OAuth. As cinco ferramentas de configuração da conta (didit_account_*) são excluídas dos servidores remotos e recusam-se a executar, porque um conector remoto nunca pode receber credenciais como argumentos de ferramentas. Um servidor stdio local mantém todas elas, num total de 193. Cada ferramenta listada inclui anotações MCP (readOnlyHint, destructiveHint, openWorldHint, um title) e um outputSchema, bem como uma etiqueta _meta["anthropic/toolGroup"] que indica a sua área (Sessões, Fluxos e Questionários, Transações (AML), e assim por diante). Clientes como o Claude usam as anotações para separar as ferramentas do conector em grupos de só leitura, de escrita e destrutivos.

​
Ramificações em fluxos

Os fluxos simples são uma lista plana de funcionalidades. Para a lógica condicional (recusar com base num estado, encaminhar com base num campo extraído, condicionar um passo a uma correspondência ou acrescentar um pedido de Document AI), o MCP trabalha com o grafo de nós do Didit (a mesma estrutura do construtor visual da consola). Um grafo é { start_node, nodes }, e cada nó é um nó feature, branch, status (terminal), action ou webhook. As regras de ramificação suportam operadores como fuzzy_match (campos de texto, com um score de semelhança de 0–100) em campos extraídos, como kyc.extra_fields.profession, e um nó de funcionalidade DOCUMENT_AI pede documentos (por exemplo, comprovativo de fundos).

​
Editar um fluxo existente (recomendado)

Os fluxos reais têm configurações de funcionalidades grandes: uma lista de permissões documents_allowed do OCR pode ter 150 KB+, além das listas de comprovativo de morada (POA) e de países de telefone. Por isso, não leia o grafo completo nem o volte a enviar. Em vez disso, edite com pequenas operações:
1

Localizar e inspecionar

didit_workflow_search { workflow_id } encontra-o em todas as suas aplicações. didit_workflow_get_graph devolve a estrutura com as configurações grandes resumidas (nunca excede o limite; passe include_config: true para obter os valores em bruto). didit_workflow_get_field_definitions lista os campos que podem ser usados em ramificações e os operadores válidos.
2

Editar com operações

didit_workflow_edit_graph recebe algumas operações pequenas (set_next, set_node, set_branches, merge_node_config). O MCP obtém o grafo completo do lado do servidor, aplica-as, valida, cria automaticamente um rascunho e guarda. As suas listas de permissões são preservadas byte a byte e nunca passam pelo pedido. Uma falha de validação devolve applied: false (nada é guardado).
3

Rever e publicar

Continua a ser um rascunho para rever até fazer publish (na consola ou através de didit_workflow_publish). A versão em produção nunca é alterada.
Por exemplo, para inserir uma ramificação depois da verificação de identidade que volte a ligar-se ao seu fluxo existente, só precisa de enviar: reencaminhar o next do nó OCR para uma nova ramificação e acrescentar a ramificação, um nó terminal Declined e um passo DOCUMENT_AI (cujo next aponta de volta para o passo seguinte original). Os outros 10 nós, e as respetivas listas de permissões, ficam intactos.
“Depois da verificação de identidade, se foi recusada, recusar; se a profissão ≈ ‘Software Engineer’ (≥80%), pedir comprovativo de fundos; depois continuar.” → um nó branch: kyc.status == Declined → um nó de estado Declined; kyc.extra_fields.profession fuzzy_match “Software Engineer” score 80 → um nó DOCUMENT_AI de comprovativo de fundos → e um caminho senão de volta ao fluxo.
Uma ramificação tem sempre de ter um senão explícito. O caso residual (o caminho seguido quando nenhuma condição é cumprida) tem de ser uma ramificação com rules vazio, por exemplo { "id": "else", "rules": [], "goto": "<liveness>" }, e não o next simples do nó de ramificação. O MCP (e o backend) convertem automaticamente o next de um nó de ramificação numa ramificação senão, para que uma ramificação nunca seja apresentada como uma ligação ambígua sem senão visível.
Para criar um fluxo novo do zero, use didit_workflow_validate_graph e depois didit_workflow_set_graph (grafo completo), ou deixe que didit_workflow_build_graph monte um grafo completo a partir de uma especificação simples de funcionalidades, sem guardar. Até um didit_workflow_create simples é guardado como este mesmo grafo de nós: o MCP transforma a sua lista features em nós de funcionalidade encadeados, que terminam num estado de decisão automática, para que as funcionalidades sejam de facto executadas (publica por defeito; passe status: "draft" para o manter não publicado). Consulte Criar fluxo → ramificações e fluxos baseados em nós para ver a estrutura JSON completa.

​
Ramificações do motivo pelo qual o NFC foi ignorado com o MCP

Para um grafo novo, peça:
“Crie um fluxo em rascunho com verificação de identidade seguida de NFC. Se nfc.skip_reason for DEVICE_WITHOUT_NFC ou DOCUMENT_WITHOUT_CHIP, envie a sessão para Em análise; caso contrário, aprove-a. Mantenha uma ramificação senão explícita e valide o grafo antes de guardar.”
O agente deve chamar didit_workflow_get_field_definitions, didit_workflow_validate_graph e, depois, didit_workflow_set_graph. Para um fluxo existente, peça:
“Edite o fluxo 26d33c04…: depois do seu nó NFC, encaminhe qualquer um dos sete valores conhecidos de nfc.skip_reason para Em análise e mantenha como senão explícito o caminho existente após uma NFC bem-sucedida. Guarde um rascunho; não o publique.”
O agente deve chamar didit_workflow_search, didit_workflow_get_graph, didit_workflow_get_field_definitions e, depois, didit_workflow_edit_graph. A ferramenta de edição aplica pequenas operações do lado do servidor, pelo que preserva os nós não relacionados e as listas de permissões grandes. Consulte Criar fluxo → Ramificar pelo motivo de o NFC não ter sido executado para ver os sete valores, as regras equals/in, o comportamento com valores nulos e um grafo completo ordenado.

​
Configurações de funcionalidades e listas de permissões

O config de um nó de funcionalidade restringe o que este aceita. didit_workflow_get_feature_config_schema devolve todas as chaves que cada funcionalidade aceita, com os respetivos tipos e valores por defeito. As duas ferramentas de catálogo (didit_workflow_get_id_verification_methods_catalog e didit_workflow_get_kyb_registry_catalog) respondem às perguntas definidas pelo servidor de que uma configuração depende. A lista de permissões OCR canónica é por país → por documento → objeto: { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (por exemplo, { "ESP": { "P": { "enabled": 1 } } }). O MCP normaliza formatos mais simples antes de validar, por isso não precisa de escrever essa estrutura manualmente: O poa_languages_allowed de PROOF_OF_ADDRESS segue a mesma ideia: passe um array de idiomas (["es"]) ou um mapa ({ "es": 1 }). Estas facilidades aplicam-se sempre que indicar ao MCP uma configuração de funcionalidade: as funcionalidades de didit_workflow_create, e os config dos nós em set_graph, edit_graph e validate_graph.

​
Formato da resposta (contrato V3)

Cada ferramenta devolve o JSON original do endpoint REST correspondente. Há duas coisas a saber:
  • Ferramentas síncronas (fluxos, faturação, verify_* autónomas, gestão de listas) devolvem o resultado final em linha: atue sobre ele no mesmo turno.
  • A criação de sessões é assíncrona: didit_session_create devolve um url que o utilizador tem de concluir; a decisão chega por webhook ou através de didit_session_get_decision.
As chaves de decisão são sempre arrays no plural, com um node_id por entrada (id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], phone_verifications[], email_verifications[], database_validations[], reviews[], além das verificações de KYB registry_checks[], document_verifications[], key_people_checks[]). Consulte Modelos de dados e Estados de verificação.

​
Processamento de webhooks

Deixe um webhook entregar a decisão final ao seu backend em vez de fazer consultas periódicas a partir do agente:
  1. O agente chama didit_webhook_create uma vez com um label, o seu url HTTPS público, webhook_version: "v3" e subscribed_events (normalmente ["status.updated", "data.updated"]). A resposta oculta o segredo de assinatura, o mesmo que acontece em didit_webhook_get e didit_webhook_list; copie-o de Webhooks na consola e guarde-o como DIDIT_WEBHOOK_SECRET.
  2. O seu backend verifica o cabeçalho canónico X-Signature-V2 em cada entrega: shortenFloats → sortKeys → JSON.stringify (unicode sem escape) → HMAC-SHA256 → timingSafeEqual. Rejeite a entrega se abs(now − X-Timestamp) > 300 segundos.
  3. Deduplique com base em event_id. Devolva 2xx em 5 segundos; mova o trabalho pesado para uma fila.
  4. A Didit volta a tentar em caso de 5xx / 404, até 2 vezes (~1 min, depois ~4 min), e depois descarta a entrega. Reenvie as que falharam a partir do separador Entregas na consola.
O agente só precisa de configurar o recetor; não fica à escuta por conta própria. Contrato completo: Webhooks.

​
Transporte e endpoints

Este endpoint suporta duas gerações de clientes: os clientes que fixam uma versão de protocolo igual ou posterior a 2026-07-28 em cada mensagem dispensam o handshake initialize e podem chamar server/discover; todos os clientes anteriores (Claude Code, Cursor, clientes baseados em SDK) usam o handshake Streamable HTTP padrão, sem alterações. O CORS está aberto, pelo que os clientes baseados em navegador (o conector web do Claude, o MCP Inspector) conseguem aceder a /mcp e aos documentos de descoberta entre origens. O limite do corpo JSON é de 25 MB, suficiente para um ficheiro em base64 de 15 MB.

​
Resolução de problemas

A sua função nessa organização não tem a permissão de que a ferramenta precisa (por exemplo, um READER a tentar uma escrita); o erro missing_scope indica qual. Se todas as ferramentas falharem, volte a ligar ou execute novamente Iniciar sessão com Didit. (O MCP só aceita Bearer/OAuth: um x-api-key é rejeitado por todas as ferramentas, por isso uma chave de API não resolve um 403.)
As ferramentas destrutivas exigem confirmação no seu cliente. Aprove a chamada ou verifique se o pedido de confirmação da ferramenta não está a ser recusado automaticamente. didit_session_delete, didit_session_batch_delete e didit_org_reveal_application_api_key exigem ainda confirm: true nos argumentos da ferramenta; sem isso, a chamada é rejeitada antes de qualquer execução.
Provavelmente tem várias aplicações. Use uma ferramenta *_search (que abrange tudo) ou execute didit_context_get e indique o organization_id / application_id pretendido.
Alguns clientes (Windsurf, Zed) ligam-se através da ponte mcp-remote. Certifique-se de que npx -y mcp-remote@latest https://mcp.didit.me/mcp está na configuração. Reabra o cliente para repetir o handshake OAuth.
Confirme que o servidor está ligado (a maioria dos clientes mostra um indicador de estado) e que concluiu Iniciar sessão com Didit. Reinicie o host MCP depois de editar a respetiva configuração. didit_org_top_up e didit_org_reveal_application_api_key nunca aparecem no conector alojado.
Certifique-se de que aponta para https://mcp.didit.me/mcp, e não para a origem simples https://mcp.didit.me: os metadados do recurso são servidos em /.well-known/oauth-protected-resource/mcp, limitados a esse caminho (com uma cópia na raiz da origem para os clientes que procuram aí). Se estiver a usar o alojamento próprio, isto geralmente significa que MCP_RESOURCE_URI está definido com a origem em vez do URL completo do transporte; consulte Alojamento próprio.
No endpoint alojado, envie o ficheiro como *_base64 (base64 puro ou um URL data:); *_path só funciona num servidor stdio local. Os ficheiros estão limitados a 15 MB e têm de ser PNG, JPG, WebP, GIF, BMP, ICO ou PDF pelo conteúdo, não apenas pela extensão.

​
Segurança

O MCP atua com as suas permissões reais e pode modificar recursos em produção. Mantenha “review tool calls before running” ativado no seu cliente, sobretudo para as ferramentas Escrita e Destrutiva. O próprio MCP não guarda nenhum segredo na sua configuração (usa Iniciar sessão com a Didit), oculta chaves de API e segredos de assinatura de webhooks no resultado das ferramentas, esconde do catálogo alojado as ferramentas de carregamento de saldo e de chave em bruto, e nunca aceita credenciais de conta como argumentos de ferramentas num servidor remoto. Cada chamada de ferramenta é registada no registo de auditoria do servidor, com o chamador, a ferramenta e o veredito de permissão.

​
Injeção de prompt

As ferramentas da Didit devolvem o que os seus utilizadores escreveram ou carregaram, como nomes, texto de documentos e respostas de questionários. A pessoa que está a ser verificada controla esse texto, por isso pode escrever instruções destinadas ao seu agente num nome ou num documento, e o servidor devolve esses campos tal como foram capturados. Um agente não consegue distinguir de forma fiável esse texto das suas próprias instruções, por isso trate cada resultado de ferramenta como dados:
  • Mantenha a aprovação de ferramentas ativada para as ferramentas Escrita e Destrutiva, e leia o que o agente vai fazer antes de aprovar.
  • Inicie sessão como membro cuja função corresponda ao trabalho. Um agente que apenas consulta sessões pode usar um membro READER, e o backend recusa as respetivas operações de escrita, independentemente do que o agente tente.
  • Experimente primeiro um novo agente ou prompt numa aplicação sandbox.
  • Nunca aprove nem recuse uma verificação porque o texto dessa verificação o indica. Baseie-se na decisão, nos avisos e na sua própria revisão.

​
Dados pessoais

Os resultados das ferramentas podem incluir dados pessoais, como nomes, datas de nascimento, números de documentos e ligações para imagens, e o seu cliente MCP envia-os para o modelo que utiliza. Antes de ligar uma aplicação em produção, verifique se o seu contrato com o fornecedor de IA cobre estes dados, ou trabalhe numa aplicação sandbox.

​
Auto-alojamento

O servidor alojado é criado a partir de github.com/didit-protocol/mcp (MIT). Clone-o e execute-o com Docker ou Node. Autentica-se sempre como utilizador da Didit (não existe modo de chave de API), em qualquer um dos transportes. Os passos de configuração estão em Instalação → auto-alojamento.

​
Variáveis de ambiente

O .env.example do repositório é um modelo para copiar, e o ARCHITECTURE.md explica a separação entre o servidor de recursos e o servidor de autorização. No arranque, o servidor HTTP obtém o documento de descoberta do servidor de autorização e recorre aos URLs configurados se este estiver inacessível.

Referência de ferramentas

Todas as ferramentas, agrupadas por área.

Exemplos

Instruções e conversas completas de início ao fim.
Última modificação em 7 de novembro de 2026