KYC Via 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 Protocolo de Contexto de Modelo (MCP) em https://mcp.didit.me/mcp as torna tão naturais quanto uma conversa. Aponte um agente de IA — Claude Desktop, Claude Code, Cursor, ChatGPT ou qualquer cliente compatível com MCP — para o endpoint hospedado, autentique-se com "Fazer login com Didit", e o agente poderá percorrer todo o ciclo de vida do KYC: descobrir sua organização e aplicativo, escolher o fluxo de trabalho correto, criar uma sessão de verificação hospedada, entregar o link ao seu usuário e consultar a decisão. Este guia detalha essa sequência ferramenta por ferramenta, aborda os 10 status de sessão e o que fazer em cada um, e mostra as chamadas REST equivalentes para leitores que desejam o caminho de backend.

Principais pontos

• O servidor Didit MCP expõe 115 ferramentas em 11 categorias via HTTP Streamable em https://mcp.didit.me/mcp. Ele é hospedado ou pode ser auto-hospedado, e a camada MCP em si é gratuita.
• A autenticação é OAuth 2.1 + Proof Key for Code Exchange (PKCE) com Registro Dinâmico de Cliente. Não há chave de API para o servidor MCP hospedado — o agente se autentica como o usuário logado e herda as permissões de console desse usuário.
• Uma verificação KYC completa — verificação de documento de identidade, 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 em menos de 2 segundos. O fluxo de trabalho pode incluir verificações adicionais como triagem AML ($0.20) ou questionários personalizados ($0.10).
• O agente executa uma sessão KYC em cinco ferramentas: descobrir sua organização e aplicativo, selecionar um fluxo de trabalho, criar a sessão, ler a decisão do array V3 e atualizar o status da sessão para aprovar, recusar ou solicitar reenvio.
• 10 status de sessão informam ao agente o que fazer em seguida: de Não Iniciado a Em Andamento, Em Revisão, Aprovado, Recusado, Expirado, Abandonado, KYC Expirado, Reenviado e Aguardando Usuário.
• O servidor MCP impulsiona o onboarding para mais 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 Protocolo de Contexto de Modelo (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. Ele usa transporte HTTP Streamable — sem estado, somente POST, sem Eventos Enviados pelo Servidor — e expõe 115 ferramentas em 11 categorias que cobrem toda a plataforma: sessões, fluxos de trabalho, APIs de verificação, monitoramento de transações, triagem Anti-Lavagem de Dinheiro (AML), triagem de carteira, webhooks, casos, relatórios e operações de espaço de trabalho.

A autenticação hospedada usa OAuth 2.1 com PKCE (Proof Key for Code Exchange) e Registro Dinâmico de Cliente (DCR). Quando o agente se conecta pela primeira vez, ele abre um navegador para o fluxo "Fazer login com Didit" através de business.didit.me. O token resultante é limitado ao seu usuário de console em didit:management e didit:verification — o agente só pode fazer o que sua função já permite. Isso é importante: não há chave de API para colar em um arquivo de configuração MCP para o servidor hospedado. Chaves de API são um conceito de API REST e não são usadas no contexto MCP.

Para conectar o endpoint hospedado ao Claude Desktop ou Claude.ai, use 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 a documentação de visão geral do MCP.

A sequência KYC — ferramenta por ferramenta

Uma sessão KYC padrão na Didit agrupa sua escolha de verificações de identidade — verificação de documento de identidade, 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 é configurado. Aqui está a sequência exata de ferramentas que um agente segue para criar, entregar e resolver uma:

1. Descubra seu contexto

Antes de criar qualquer coisa, o agente precisa saber em qual organização e aplicativo operar. Chame didit_context_get para listar as organizações e aplicativos disponíveis aos quais o usuário logado tem acesso. Isso retorna o organization_id e o application_id que toda chamada de ferramenta subsequente precisa.

2. Escolha 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 seu aplicativo. Cada fluxo de trabalho expõe seus recursos — OCR (Reconhecimento Óptico de Caracteres), Prova de Vida, Correspondência Facial, AML, questionários — para que o agente possa escolher o correto para o tipo de verificação necessário. Para um onboarding KYC padrão, o fluxo de trabalho geralmente inclui OCR, Prova de Vida, Correspondência Facial e Análise de IP.

3. Crie a sessão

Com o fluxo de trabalho selecionado, chame didit_session_create com o workflow_id e, opcionalmente, sua própria referência externa em vendor_data. O escopo da organização e do aplicativo se resolve automaticamente quando são inequívocos, então você raramente os passa. Você também pode definir o language para a UI de verificação hospedada, um callback para o qual o solicitante retorna e dados pré-preenchidos via contact_details ou expected_details. A ferramenta retorna uma url — um link hospedado que você envia ao solicitante. Nenhuma integração de SDK é necessária para este caminho; o solicitante simplesmente abre o link em seu navegador, completa as verificações e o agente continua a partir daí.

4. Leia a decisão

Assim que o solicitante 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 recurso (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. Aja com base na decisão

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

• Aprovado — todas as verificações foram aprovadas. Defina o status como approved para finalizar.
• Recusado — verificações falharam ou fraude detectada. Defina o status como declined.
• Reenviado — documentos estavam pouco claros ou o solicitante precisa tentar novamente. Defina o status como resubmitted para permitir outra tentativa.

Essa é a jornada completa do KYC em cinco ferramentas, tudo a partir de um prompt em linguagem natural.

Os 10 status de sessão

As sessões Didit passam por um ciclo de vida de 10 status. Um agente configurado para monitorar sessões deve lidar com cada um:

• Não Iniciado — a sessão foi criada, mas o solicitante não abriu o link de verificação. Nenhuma ação necessária ainda.
• Em Andamento — o solicitante abriu o link e está passando 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 o onboarding.
• Recusado — verificações falharam. Rejeite o solicitante 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 solicitante 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 re-onboarding.
• Reenviado — o solicitante reenviou depois de ser solicitado a fornecer dados melhores. Reexecute didit_session_get_decision para obter o novo veredito.
• Aguardando Usuário — a sessão está pausada aguardando que o solicitante forneça informações ou documentos adicionais.

Controles de nível de agente: listas, listas de bloqueio e monitoramento contínuo

Além do KYC de sessão única, o servidor MCP dá aos agentes acesso à superfície de controle de risco. Use didit_lists_list e didit_lists_entry_create para adicionar solicitantes recusados a listas de bloqueio, impedindo-os de criar novas sessões. Use didit_blocklist_get e didit_blocklist_add para rastrear novas solicitações de sessão antes que sejam criadas. Para monitoramento contínuo, após uma aprovação KYC, você pode executar didit_verify_aml para triagem Anti-Lavagem de Dinheiro contra mais de 1.300 listas de observação a $0.20 por verificação, e didit_transaction_screen_wallet para triagem de carteira de criptomoedas a $0.15 por verificação.

Caminho equivalente da API REST

Nem toda integração é feita através de um agente de IA. Se você está construindo um backend que chama Didit diretamente via HTTP, a API REST usa autenticação x-api-key (a chave secreta do seu aplicativo do console). Aqui está a criação equivalente de sessão KYC via curl:

curl -X POST https://api.didit.me/v3/session/ \
  -H "x-api-key: SUA_CHAVE_API" \
  -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 a url — o mesmo link hospedado que a sessão MCP retorna. Consulte o endpoint de decisão e atualize o status 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 ao fluxo OAuth MCP descrito acima. A API REST é uma superfície separada; o servidor MCP nunca precisa ou usa uma chave de API.

Preços e limites

Cada recurso Didit tem preços publicados, por sucesso, sem mínimos. O servidor MCP em si é gratuito — não há cobrança para conectar ou listar ferramentas. Você 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
• Triagem AML: $0.20 por verificação, mais de 1.300 listas de observação
• Triagem de carteira (KYT): $0.15 por verificação
• Monitoramento de transações: $0.02 por transação
• Verificação de Negócios (KYB): a partir de $2.00 por negócio

Cada recurso inclui 500 verificações gratuitas por mês, para sempre. Sem limite de tempo, sem restrição de nível. O pacote KYC completo por $0.33 é 3 a 5 vezes mais barato do que os provedores de KYC tradicionais, com inferência p99 em menos de 2 segundos em mais de 220 países e 14.000 tipos de documentos.

Primeiros passos

Para conectar 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 o prompt: "Descobrir minha organização e aplicativos, listar os fluxos de trabalho KYC e criar uma sessão de verificação para um novo solicitante."

O código-fonte do MCP é aberto e licenciado pelo MIT em github.com/didit-protocol/mcp. Para um passo a passo mais aprofundado da instalação do 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.