KYC Através de um Servidor MCP: O Guia Prático

As verificações Know Your Customer (KYC) são a operação de identidade mais comum na plataforma Didit, e o servidor oficial do Model Context Protocol (MCP) em https://mcp.didit.me/mcp torna a sua execução tão natural quanto uma conversa. Aponte um agente de IA — Claude Desktop, Claude Code, Cursor, ChatGPT, ou qualquer cliente compatível com MCP — para o endpoint alojado, autentique-se com “Iniciar sessão com Didit”, e o agente pode percorrer todo o ciclo de vida KYC: descobrir a sua organização e aplicação, escolher o fluxo de trabalho certo, criar uma sessão de verificação alojada, entregar o link ao seu utilizador e consultar a decisão. Este guia descreve essa sequência ferramenta a ferramenta, abrange os 10 estados da sessão e o que fazer em cada um, e mostra as chamadas REST equivalentes para leitores que desejam o caminho de backend.

Principais conclusões

• O servidor Didit MCP expõe 115 ferramentas em 11 categorias através de HTTP Transmissível em https://mcp.didit.me/mcp. É alojado ou auto-alojado, e a camada MCP em si é gratuita.
• A autenticação é OAuth 2.1 + Proof Key for Code Exchange (PKCE) com Registo Dinâmico de Cliente. Não existe chave API para o servidor MCP alojado — o agente autentica-se como o utilizador com sessão iniciada e herda as permissões da consola desse utilizador.
• Uma verificação KYC completa — verificação de documento de identificação, prova de vida passiva, correspondência facial e análise de IP — custa 0,33€, com 500 verificações gratuitas por mês e inferência p99 abaixo de 2 segundos. O fluxo de trabalho pode incluir verificações adicionais como rastreio AML (0,20€) ou questionários personalizados (0,10€).
• O agente executa uma sessão KYC em cinco ferramentas: descobrir a sua organização e aplicação, selecionar um fluxo de trabalho, criar a sessão, ler a decisão do array V3 e atualizar o estado da sessão para aprovar, recusar ou solicitar reenvio.
• 10 estados da sessão indicam ao agente o que fazer a seguir: desde Não Iniciado até Em Progresso, Em Revisão, Aprovado, Recusado, Expirado, Abandonado, KYC Expirado, Reenviado e Aguardando Utilizador.
• O servidor MCP alimenta a integração de 2.000+ empresas em produção em mais de 220 países e 14.000+ tipos de documentos, em mais de 48 idiomas.

O que é o servidor Didit MCP

O Model Context Protocol (MCP) é um padrão aberto que permite que agentes de IA chamem ferramentas externas através de uma interface consistente. A implementação da Didit em https://mcp.didit.me/mcp é o servidor MCP oficial para a plataforma de identidade e fraude, publicado sob a licença MIT em github.com/didit-protocol/mcp. Utiliza transporte HTTP Transmissível — sem estado, apenas POST, sem Server-Sent Events — e expõe 115 ferramentas em 11 categorias que cobrem toda a plataforma: sessões, fluxos de trabalho, APIs de verificação, monitorização de transações, rastreio Anti-Lavagem de Dinheiro (AML), rastreio de carteira, webhooks, casos, relatórios e operações de espaço de trabalho.

A autenticação alojada utiliza OAuth 2.1 com PKCE (Proof Key for Code Exchange) e Dynamic Client Registration (DCR). Quando o agente se conecta pela primeira vez, abre um navegador para o fluxo “Iniciar sessão com Didit” através de business.didit.me. O token resultante é limitado ao seu utilizador da consola através de didit:management e didit:verification — o agente só pode fazer o que a sua função já permite. Isto é importante: não há chave API para colar num ficheiro de configuração MCP para o servidor alojado. As chaves API são um conceito de API REST e não são usadas no contexto MCP.

Para conectar o endpoint alojado ao Claude Desktop ou Claude.ai, utilize o link direto do conector pré-construído:

Adicionar Didit como um conector Claude

Para uma visão geral do conjunto completo de ferramentas, consulte a referência de ferramentas MCP e os documentos de visão geral do MCP.

A sequência KYC — ferramenta a ferramenta

Uma sessão KYC padrão na Didit agrupa a sua escolha de verificações de identidade — verificação de documento de identificação, prova de vida passiva para confirmar que a pessoa está fisicamente presente, correspondência facial para confirmar que a selfie corresponde ao retrato do documento e análise de IP para sinais de fraude — tudo por 0,33€ quando o pacote completo está configurado. Aqui está a sequência exata de ferramentas que um agente segue para criar, entregar e resolver uma:

1. Descobrir o seu contexto

Antes de criar qualquer coisa, o agente precisa de saber em qual organização e aplicação operar. Chame didit_context_get para listar as organizações e aplicações disponíveis às quais o utilizador com sessão iniciada tem acesso. Isso retorna o organization_id e application_id que todas as chamadas de ferramenta subsequentes precisam.

2. Escolher um fluxo de trabalho

Os fluxos de trabalho de verificação definem quais verificações são executadas e como as decisões são tomadas. Chame didit_workflow_list para buscar os fluxos de trabalho configurados para a sua aplicação. Cada fluxo de trabalho expõe as suas funcionalidades — OCR (Reconhecimento Ótico de Caracteres), Prova de Vida, Correspondência Facial, AML, questionários — para que o agente possa escolher o mais adequado para o tipo de verificação necessário. Para uma integração KYC padrão, o fluxo de trabalho tipicamente inclui OCR, Prova de Vida, Correspondência Facial e Análise de IP.

3. Criar a sessão

Com o fluxo de trabalho selecionado, chame didit_session_create com o workflow_id e, opcionalmente, a sua própria referência externa em vendor_data. O âmbito da organização e da aplicação resolve-se automaticamente quando são inequívocos, por isso raramente os passa. Também pode definir o language para a interface de utilizador de verificação alojada, um callback para onde o candidato retorna, e dados pré-preenchidos via contact_details ou expected_details. A ferramenta retorna um url — um link alojado que envia ao candidato. Nenhuma integração SDK é necessária para este caminho; o candidato apenas abre o link no seu navegador, completa as verificações, e o agente continua a partir daí.

4. Ler a decisão

Assim que o candidato concluir as verificações, chame didit_session_get_decision com o ID da sessão. Isso retorna uma decisão de array plural V3: uma string status, um objeto decision com veredito e pontuação de risco, e resultados por funcionalidade (dados OCR, confiança da prova de vida, similaridade da correspondência facial, etc.). O agente lê o veredito para determinar a próxima ação.

5. Agir com base na decisão

Chame didit_session_update_status para definir o estado da sessão com base no veredito da decisão:

• Aprovado — todas as verificações foram aprovadas. Defina o estado para approved para finalizar.
• Recusado — as verificações falharam ou foi detetada fraude. Defina o estado para declined.
• Reenviado — os documentos estavam pouco claros ou o candidato precisa de tentar novamente. Defina o estado para resubmitted para permitir outra tentativa.

Essa é toda a jornada KYC em cinco ferramentas, tudo a partir de um comando em linguagem natural.

Os 10 estados da sessão

As sessões Didit movem-se através de um ciclo de vida de 10 estados. Um agente configurado para monitorizar sessões deve lidar com cada um:

• Não Iniciado — a sessão foi criada, mas o candidato não abriu o link de verificação. Nenhuma ação necessária ainda.
• Em Progresso — o candidato abriu o link e está a passar pelas verificações. O agente deve esperar.
• Em Revisão — as verificações automatizadas terminaram com uma pontuação limítrofe; a sessão precisa de revisão manual. Notifique um oficial de conformidade humano.
• Aprovado — todas as verificações foram aprovadas. Conclua a integração.
• Recusado — as verificações falharam. Rejeite o candidato ou inicie uma nova verificação com documentos diferentes.
• Expirado — a sessão expirou antes da conclusão. Ofereça uma nova sessão.
• Abandonado — o candidato fechou o fluxo antes de terminar. Envie um lembrete ou um novo link.
• KYC Expirado — uma sessão de reverificação periódica expirou. Sinalize para nova integração.
• Reenviado — o candidato reenviou após ser solicitado a fornecer dados melhores. Volte a executar didit_session_get_decision para obter o novo veredito.
• Aguardando Utilizador — a sessão está em pausa à espera que o candidato forneça informações ou documentos adicionais.

Controlos ao nível do agente: listas, listas de bloqueio e monitorização contínua

Além do KYC de sessão única, o servidor MCP dá aos agentes acesso à superfície de controlo de risco. Use didit_lists_list e didit_lists_entry_create para adicionar candidatos recusados a listas de bloqueio, impedindo-os de criar novas sessões. Use didit_blocklist_get e didit_blocklist_add para rastrear novos pedidos de sessão antes de serem criados. Para monitorização contínua, após uma aprovação KYC, pode executar didit_verify_aml para rastreio Anti-Lavagem de Dinheiro contra mais de 1.300 listas de vigilância a 0,20€ por verificação, e didit_transaction_screen_wallet para rastreio de carteira de criptomoedas a 0,15€ por verificação.

Caminho equivalente da API REST

Nem toda a integração é feita através de um agente de IA. Se estiver a construir um backend que chama a Didit diretamente via HTTP, a API REST usa autenticação x-api-key (a chave secreta da sua aplicação a partir da consola). Aqui está a criação de sessão KYC equivalente via curl:

curl -X POST https://api.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wfl_abc123",
    "vendor_data": "user-456",
    "language": "en",
    "callback": "https://myapp.com/kyc-callback"
  }'

A resposta inclui o session_id e o url — o mesmo link alojado que a sessão MCP retorna. Consulte o endpoint de decisão e atualize o estado da mesma forma, mas via REST. Observe o cabeçalho x-api-key: este é o mecanismo de autenticação da API REST e não está relacionado com o fluxo OAuth MCP descrito acima. A API REST é uma superfície separada; o servidor MCP nunca precisa ou usa uma chave API.

Preços e limites

Cada funcionalidade Didit tem preços publicados por sucesso, sem mínimos. O próprio servidor MCP é gratuito — não há cobrança pela conexão ou listagem de ferramentas. Paga apenas por verificações bem-sucedidas:

• Pacote KYC completo (ID + Prova de Vida Passiva + Correspondência Facial + IP): 0,33€
• Verificação de ID (autónoma): 0,15€
• Prova de vida passiva (autónoma): 0,10€
• Rastreio AML: 0,20€ por verificação, mais de 1.300 listas de vigilância
• Rastreio de carteira (KYT): 0,15€ por verificação
• Monitorização de transações: 0,02€ por transação
• Verificação de Negócios (KYB): a partir de 2,00€ por negócio

Cada funcionalidade inclui 500 verificações gratuitas por mês, para sempre. Sem limite de tempo, sem portão de nível. O pacote KYC completo a 0,33€ é 3-5x mais barato do que os fornecedores KYC tradicionais, com inferência p99 abaixo de 2 segundos em mais de 220 países e 14.000+ tipos de documentos.

Primeiros passos

Para conectar o seu agente e começar a executar verificações KYC em minutos:

1. Abra o link direto do conector Claude e adicione Didit como um conector personalizado.
2. Para Claude Code: execute claude mcp add --transport http didit https://mcp.didit.me/mcp, depois /mcp para autenticar.
3. Para Cursor: adicione {"mcpServers":{"didit":{"url":"https://mcp.didit.me/mcp"}}} a .cursor/mcp.json.
4. Uma vez autenticado, digite: "Descubra a minha organização e aplicações, liste os fluxos de trabalho KYC e crie uma sessão de verificação para um novo candidato."

O código-fonte do MCP é aberto e licenciado sob MIT em github.com/didit-protocol/mcp. Para um guia mais aprofundado sobre como instalar o servidor em diferentes clientes, leia Como Instalar o Servidor Didit MCP no Claude. Para o catálogo completo de ferramentas com parâmetros, consulte a Referência de Ferramentas Didit MCP.