MCP Server

O CPFHub.io tem um servidor Model Context Protocol remoto em https://api.cpfhub.io/mcp. Ele permite que agentes de IA como Claude, Cursor e outros clientes MCP consultem CPF e CNPJ, rodem lotes e criem verificações de identidade durante a conversa, sem instalar nada.

O que é o MCP?

O Model Context Protocol (MCP) é um protocolo aberto que permite que LLMs chamem ferramentas externas de forma padronizada. Com o servidor MCP do CPFHub.io, o agente pode chamar as nove tools listadas abaixo e receber os dados diretamente na resposta.

Instalação

Use o servidor remoto (https://api.cpfhub.io/mcp), que não exige instalação e tem todas as tools. O pacote local npx @cpfhub/mcp existe apenas para clientes sem suporte a HTTP e tem limitações (veja abaixo).

Configuração

O CPFHub.io suporta dois modos de conexão: remoto (recomendado, sem instalação) e local (via npx, alternativa para clientes sem suporte a HTTP).

Remoto: HTTP Streamable (recomendado)

Funciona em qualquer cliente MCP que suporte conexões HTTP (Streamable HTTP). Não requer Node.js instalado. A API Key vai no header x-api-key ou, para clientes que não aceitam headers, na URL como ?api_key=.

Claude Desktop e claude.ai: servidores remotos não entram no claude_desktop_config.json (esse arquivo é só para servidores locais). Adicione como conector:

1. Abra Configurações > Conectores e clique em Adicionar conector personalizado.
2. Nome: CPFHub.io. URL: https://api.cpfhub.io/mcp?api_key=SUA_API_KEY.
3. Salve e ative o conector na conversa.

Claude Code (via terminal):

claude mcp add cpfhub --transport http https://api.cpfhub.io/mcp --header "x-api-key: $CPFHUB_API_KEY"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cpfhub": {
      "url": "https://api.cpfhub.io/mcp",
      "headers": { "x-api-key": "SUA_API_KEY" }
    }
  }
}

Para testar a conexão e a chave sem gastar créditos, liste as tools com curl:

curl -s https://api.cpfhub.io/mcp \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A resposta deve listar as nove tools: lookup_cpf, lookup_cpf_realtime, lookup_cnpj, bulk_lookup_cpf, bulk_lookup_cnpj, get_bulk_job, create_kyc_link, get_kyc_link e get_quota_info.

Local: stdio via npx

Use somente quando o cliente MCP não suportar HTTP. O servidor roda na sua máquina, mas cada consulta chama a API da CPFHub.io, então precisa de internet e de uma API Key.

Claude Desktop ou Cursor (via npx):

{
  "mcpServers": {
    "cpfhub": {
      "command": "npx",
      "args": ["-y", "@cpfhub/mcp"],
      "env": {
        "CPFHUB_API_KEY": "SUA_API_KEY"
      }
    }
  }
}

Variável de ambiente (local)

export CPFHUB_API_KEY=SUA_API_KEY
npx @cpfhub/mcp

Tools disponíveis

lookup_cpf

Consulta Simples: retorna nome, gênero e data de nascimento a partir da base da CPFHub.io (mesmos dados de GET /cpf/{cpf}). Consome o custo de uma Consulta Simples do seu plano (1 crédito por padrão) por CPF encontrado. CPF não encontrado não consome crédito.

Parâmetros:

Resposta (conteúdo de texto da tool, em JSON):

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

Em caso de erro, a tool retorna isError: true e error como string:

{
  "success": false,
  "error": "CPF não encontrado na base de dados"
}

Quando o limite de requisições por minuto é atingido, o erro vem com retry_after (segundos de espera):

{
  "success": false,
  "error": "Limite de requisições por minuto excedido. Tente novamente em 12 segundos.",
  "retry_after": 12
}

lookup_cpf_realtime

Consulta em Tempo Real: consulta a Receita Federal no momento da chamada e retorna nome, data de nascimento, ano do óbito, situação cadastral, código de controle e comprovante (mesmos dados de POST /cpf/realtime). Consome 1,5 crédito por consulta bem-sucedida por padrão; consulte o custo do seu plano no dashboard. Só no servidor remoto.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/...",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/..."
  }
}

deathYear sempre vem na resposta como inteiro ou null. É null quando não há óbito registrado ou quando o valor recebido é inválido: precisa ter 4 dígitos, estar entre 1900 e o ano atual e não ser anterior ao ano de nascimento.

Os erros seguem o mesmo formato de lookup_cpf (isError: true, error como string), com as mensagens de POST /cpf/realtime. Data de nascimento divergente e indisponibilidade da Receita Federal não consomem crédito.

lookup_cnpj

Consulta de CNPJ: razão social, situação cadastral, endereço, CNAEs e sócios (mesmos dados de GET /cnpj/{cnpj}). Consome o custo de uma Consulta Simples do seu plano (1 crédito por padrão) por CNPJ encontrado. CNPJ inválido ou não encontrado não consome crédito.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "cnpj": "11222333000181",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "nome_fantasia": "EXEMPLO",
    "situacao_cadastral": "Ativa",
    "uf": "SP",
    "municipio": "SAO PAULO",
    "QSA": [
      { "nome_socio": "FULANO DE TAL", "qualificacao_socio": "Sócio-Administrador" }
    ]
  }
}

A resposta completa tem os mesmos campos de GET /cnpj/{cnpj}.

bulk_lookup_cpf

Cria um lote de CPFs (mesmo comportamento de POST /cpf/bulk) e responde na hora com o jobId. Até 10.000 CPFs por lote; inválidos e duplicados são descartados. Exige saldo para todos os CPFs válidos, mas só cobra a Consulta Simples de cada CPF encontrado. Não encontrados, inválidos e duplicados não consomem crédito.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}

Depois, chame get_bulk_job com o jobId para acompanhar o lote.

bulk_lookup_cnpj

Cria um lote de CNPJs (mesmo comportamento de POST /cnpj/bulk). Mesmos limites, resposta e regras de crédito de bulk_lookup_cpf.

Parâmetros:

get_bulk_job

Status e resultados de um lote (mesmos dados de GET /cpf/bulk/{jobId} e GET /cnpj/bulk/{jobId}). Chame de novo até status ser done ou failed; durante processing os resultados parciais já aparecem. No lote de CNPJ, a lista vem em cnpjs, com {cnpj, found, data}. Não consome crédito.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "cpfs": [
      { "cpf": "12345678909", "found": true, "name": "Fulano de Tal", "nameUpper": "FULANO DE TAL", "gender": "M", "birthDate": "15/06/1990", "day": 15, "month": 6, "year": 1990 },
      { "cpf": "52998224725", "found": false, "name": null, "nameUpper": null, "gender": null, "birthDate": null, "day": null, "month": null, "year": null }
    ]
  }
}

create_kyc_link

Cria um link de verificação de identidade (mesmo comportamento de POST /kyc/links). Envie a url para a pessoa: ela faz a selfie com prova de vida e fotografa o documento. Criar o link não consome crédito; cada verificação concluída consome o preço de Verificação de Identidade do seu plano (5 créditos por padrão), aprovada ou não.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": "https://verificar.cpfhub.io/v/...",
    "externalId": "cliente-4821",
    "expiresAt": "2026-10-29T14:00:00.000Z",
    "maxAttempts": 3,
    "language": "pt-BR"
  }
}

get_kyc_link

Status e decisão de um link (mesmos dados de GET /kyc/links/{id}). status do link: pending, completed, canceled ou expired; verification.status: approved, rejected ou manual_review. Não devolve dados pessoais e não consome crédito.

Parâmetros:

Resposta:

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": null,
    "externalId": "cliente-4821",
    "status": "completed",
    "attempts": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-10-29T14:00:00.000Z",
    "createdAt": "2026-10-28T14:00:00.000Z",
    "completedAt": "2026-10-28T14:06:12.000Z",
    "verification": {
      "id": "8f3c2a1e-77b0-4d3c-9a1f-0e5b6c7d8e9f",
      "status": "approved",
      "reasons": [],
      "completedAt": "2026-10-28T14:06:12.000Z"
    }
  }
}

get_quota_info

Retorna o plano, os créditos restantes e usados, o status de cobrança e os identificadores da conta. Não consome crédito e funciona mesmo com saldo zerado.

Resposta:

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

billingStatus indica a elegibilidade ao plano: active quando a conta tem uma assinatura que dá acesso ao plano, inclusive assinatura no plano Gratuito e status como past_due; free quando não há assinatura válida, por exemplo canceled, unpaid ou incomplete_expired. Nesse caso, plan pode vir como unknown. Os custos padrão são 1 crédito por Consulta Simples e 1,5 crédito por Consulta em Tempo Real; os custos e as regras de excedente específicas do seu plano ficam no dashboard. Os limites padrão são 30/min na Consulta Simples (cada envio de lote conta como 1) e 5/min na Consulta em Tempo Real. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io. Acima do limite, a API responde 429 com o header Retry-After.

Disponível também via REST: GET /quota, com o mesmo payload.

Definição da tool (para uso manual)

Se quiser usar a tool em prompts de sistema sem o servidor MCP:

{
  "name": "lookup_cpf",
  "description": "Retrieve identity data (full name, gender, date of birth) from a Brazilian CPF number using the CPFHub.io API",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)"
      }
    },
    "required": ["cpf"]
  }
}

Exemplo de uso no Claude

Com o servidor MCP configurado, você pode simplesmente pedir ao Claude:

"Valide o CPF 123.456.789-09 e me diga o nome e a data de nascimento do titular."

O Claude chamará automaticamente lookup_cpf e incluirá os dados na resposta.

Repositório

• github.com/cpfhub/cpfhub-mcp: código-fonte e issues do pacote local
• npm: @cpfhub/mcp: versões do pacote local

Atualizado em 28 de outubro de 2026