Servidor MCP

A CPFHub.io oferece suporte ao Model Context Protocol (MCP), permitindo que modelos de IA e ferramentas compatíveis consultem CPFs diretamente através de um protocolo padronizado.

Stateless Mesma API key da RESTMCP Streamable HTTP

Endpoint

POSThttps://api.cpfhub.io/mcp

O endpoint aceita todos os métodos HTTP (GET, POST, PUT, DELETE) conforme a especificação MCP Streamable HTTP.

Autenticação

A autenticação é feita via API Key, que pode ser enviada de duas formas. A mesma API key utilizada na API REST funciona para o MCP.

Header (recomendado)

x-api-key: <sua-api-key>

Query parameter

?api_key=<sua-api-key>

A autenticação e cobrança seguem exatamente as mesmas regras da REST API: API key deve estar ativa, usuário ativo, assinatura habilitada e créditos disponíveis.

Ferramentas Disponíveis

lookup_cpfConsulta informações de um CPF brasileiro

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`cpf`	string	Sim	CPF a ser consultado (apenas números ou formatado, ex: `123.456.789-00`)
`api_key`	string	Não	API key (opcional se já fornecida via header)

Resposta de Sucesso

200 OK

{
  "success": true,
  "data": {
    "cpf": "12345678900",
    "name": "NOME COMPLETO",
    "gender": "M",
    "birthDate": "01/01/1990",
    "day": 1,
    "month": 1,
    "year": 1990
  }
}

Erros Possíveis

Erro	Descrição
`API Key não fornecida`	Nenhuma API key foi informada na requisição.
`API Key inválida`	A API key não existe ou está desativada.
`Usuário inativo`	A conta do usuário foi desativada.
`Limite de créditos excedido`	Saldo de consultas esgotado.
`CPF inválido`	O CPF não possui 11 dígitos válidos.
`CPF não encontrado na base de dados`	O CPF não existe na base. Não consome crédito.

Cada consulta bem-sucedida consome 1 crédito do plano.

CPFs não encontrados na base de dados não consomem crédito.

get_quota_infoRetorna saldo de créditos e informações do plano

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`api_key`	string	Não	API key (opcional se já fornecida via header)

Resposta de Sucesso

200 OK

{
  "success": true,
  "data": {
    "plan": "Professional",
    "remainingCredits": 4500,
    "billingStatus": "Active",
    "userId": "uuid",
    "email": "[email protected]"
  }
}

Esta ferramenta não consome créditos.

Configuração em Clientes MCP

Configure o servidor CPFHub MCP no seu cliente de IA preferido.

Execute no terminal — um único comando configura tudo:

Terminal

claude mcp add cpfhub \
  --url https://api.cpfhub.io/mcp \
  --header "x-api-key: <sua-api-key>"

Detalhes Técnicos

Protocolo	`MCP Streamable HTTP (stateless)`
SDK	`@modelcontextprotocol/sdk v1.26.0`
Formato de resposta	`JSON encapsulado no formato MCP (content array)`
Sessão	`Não mantém estado entre requisições`
Rate limiting	`Controlado pelo saldo de créditos do plano`

REST API vs MCP

Aspecto	REST API	MCP
Protocolo	`HTTP REST`	`MCP over HTTP`
Autenticação	`x-api-key header/query`	`x-api-key header/query`
Cobrança por consulta	`1 crédito`	`1 crédito`
Ferramentas	`1 endpoint GET`	`2 tools (lookup_cpf, get_quota_info)`
Integração	`Qualquer HTTP client`	`Clientes MCP (Claude, Cursor, etc.)`
Sessão	`Stateless`	`Stateless`
Formato de resposta	`JSON direto`	`JSON dentro do formato MCP`

Ver página MCP completa Ver referência da REST API