> ## 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. # MCP da Didit: avançado, resolução e alojamento próprio > Na Didit MCP: funções e permissões, comportamento entre aplicações, webhooks, transporte, resolução de problemas e alojamento próprio. ## Â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](https://docs.didit.me/pt/integration/mcp/tools.md) 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`: | Modo | Comportamento | | - | - | | `shadow` (predefinido) | Todas as ferramentas são listadas; uma chamada que a sua função não pode fazer segue para o backend, que responde com `403`. O veredicto é registado no registo de auditoria do servidor. | | `enforce` | As ferramentas que a sua função não pode executar ficam de fora de `tools/list`; chamar uma delas devolve um erro `missing_scope` que indica a permissão. | | `off` | Sem verificação prévia. | 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. > [!NOTE] > > **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": "" }`, 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](https://docs.didit.me/pt/management-api/workflows/create.md) 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](https://docs.didit.me/pt/management-api/workflows/create.md#ramificar-com-base-no-motivo-pelo-qual-o-nfc-não-foi-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: `{ "": { "": { "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: | Pode passar | Normalizado para | | - | - | | Um array de tipos de documento, como `["PASSPORT"]` | esse documento para **todos** os países (apenas passaporte em todo o mundo) | | **Nomes** ou **códigos** de documentos: `PASSPORT`/`P`, `NATIONAL_ID`/`ID`, `DRIVER_LICENSE`/`DL`, `RESIDENCE_PERMIT`/`RP` (também `SSC`, `HIC`, `TC`) | o código canónico | | Uma chave de país `"ALL"`, como `{ "ALL": { "P": 1 } }` | aplicado a todos os países | | Indicadores escalares, como `{ "ESP": { "P": 1 } }` | `{ "ESP": { "P": { "enabled": 1 } } }` | | Omitido por completo | todos os documentos, todos os países | 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](https://docs.didit.me/pt/reference/data-models.md) e [Estados de verificação](https://docs.didit.me/pt/integration/verification-statuses.md). *** ## 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](https://docs.didit.me/pt/integration/webhooks.md). *** ## Transporte e endpoints | Endpoint | Finalidade | | - | - | | `POST https://mcp.didit.me/mcp` | O endpoint MCP (Streamable HTTP). `GET` e `DELETE` respondem `405`: o servidor não guarda estado, cria uma nova instância de servidor por pedido e não mantém nenhum fluxo nem sessão iniciados pelo servidor que seja necessário encerrar. | | `GET https://mcp.didit.me/healthz` | Verificação de estado: `{ "status": "ok", "service": "didit-mcp-server", "version": "5.1.1" }`. | | `GET https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` | Metadados de recurso protegido RFC 9728 (também servidos na raiz da origem). | 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 > [accordion] O agente chama uma ferramenta e recebe um 403 ou missing\_scope > > 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.) > [accordion] Uma escrita ou eliminação não foi executada > > 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. > [accordion] 'organization\_id is required' ou sem resultados > > 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. > [accordion] O navegador não abriu para iniciar sessão (alojado) > > 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. > [accordion] As ferramentas não aparecem no cliente > > 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. > [accordion] O VS Code (ou outro cliente) não consegue descobrir o OAuth ou nunca abre o navegador > > 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](#auto-alojamento). > [accordion] Um upload de ficheiro foi rejeitado > > 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](https://docs.didit.me/pt/integration/sandbox-testing.md). * 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](https://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](https://docs.didit.me/pt/integration/mcp/installation.md#alojamento-próprio). ```bash theme={null} git clone https://github.com/didit-protocol/mcp.git && cd mcp # Docker (recommended) — serves /mcp + /healthz on port 3000 docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp # …or with Node npm install && npm run build node dist/http.js # hosted HTTP/OAuth DIDIT_ACCESS_TOKEN= node dist/index.js # stdio (headless) ``` ### Variáveis de ambiente | Variável | Modo | Finalidade | | - | - | - | | `DIDIT_ACCESS_TOKEN` | stdio | O token de acesso Bearer do utilizador, para execuções sem interface. | | `DIDIT_API_BASE_URL` | ambos | Base da API de verificação (predefinida `https://verification.didit.me/v3`). | | `DIDIT_AUTH_BASE_URL` | ambos | Base da API de autenticação (predefinida `https://apx.didit.me/auth/v2`). | | `MCP_PORT` | alojado | Porta de escuta HTTP (predefinida `3000`). | | `MCP_RESOURCE_URI` | alojado | URL pública do transporte, incluindo o caminho (por exemplo `https://mcp.example.com/mcp`). O URL dos metadados RFC 9728 é derivado deste. | | `MCP_AUTHORIZATION_SERVER_ORIGIN` | alojado | Origem do servidor de autorização (predefinida `https://business.didit.me`). | | `MCP_TOKEN_VERIFY_MODE` | alojado | `introspection` (predefinido; tokens opacos) ou `jwks` (tokens de acesso JWT). | | `MCP_OAUTH_INTROSPECT_URL` | alojado | Endpoint de introspeção RFC 7662. | | `MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET` | alojado | Credenciais de autenticação básica que o servidor de recursos usa para chamar a introspeção. Forneça-as a partir de um gestor de segredos. | | `MCP_SCOPES_SUPPORTED` | alojado | Âmbitos anunciados nos metadados (predefinidos `didit:management didit:verification`). | | `MCP_DEFAULT_ORG` / `MCP_DEFAULT_APP` | ambos | Preenchem automaticamente o âmbito em implementações de um único inquilino. | | `DIDIT_AUTH_ISSUER`, `DIDIT_OIDC_DISCOVERY_URL`, `DIDIT_OIDC_AUTHORIZE_URL`, `DIDIT_OIDC_TOKEN_URL`, `DIDIT_OIDC_REGISTRATION_URL` | alojado | Substituições dos metadados do servidor de autorização; só são necessárias quando este publica os seus endpoints noutro local que não os predefinidos da origem. | | `DIDIT_JWKS_URL` | alojado | JWKS usado quando `MCP_TOKEN_VERIFY_MODE=jwks`. | | `MCP_PERMISSION_MODE` | ambos | Verificação prévia de permissões por ferramenta: `shadow` (predefinido), `enforce` ou `off`. | | `MCP_JSON_BODY_LIMIT` | alojado | Limite do corpo JSON-RPC (predefinido `25mb`). | 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. *** > [card] [Referência de ferramentas](https://docs.didit.me/pt/integration/mcp/tools.md) > > Todas as ferramentas, agrupadas por área. > [card] [Exemplos](https://docs.didit.me/pt/integration/mcp/examples.md) > > Instruções e conversas completas de início ao fim. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.