CPFHub.io

MCP Server

CPFHub.io has a remote Model Context Protocol server at https://api.cpfhub.io/mcp. It lets AI agents such as Claude, Cursor and other MCP clients look up CPFs (Brazil's individual taxpayer ID) and CNPJs, run batches and create identity verifications during the conversation, with nothing to install.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that lets LLMs call external tools in a standard way. With the CPFHub.io MCP server, the agent can call the nine tools listed below and get the data directly in its answer.

Installation

Use the remote server (https://api.cpfhub.io/mcp), which needs no installation and has every tool. The local package npx @cpfhub/mcp exists only for clients without HTTP support and has limitations (see below).

Configuration

CPFHub.io supports two connection modes: remote (recommended, no installation) and local (through npx, an alternative for clients without HTTP support).

Works in any MCP client that supports HTTP connections (Streamable HTTP). It does not require Node.js. The API key goes in the x-api-key header or, for clients that do not accept headers, in the URL as ?api_key=.

Claude Desktop and claude.ai: remote servers do not go in claude_desktop_config.json (that file is only for local servers). Add it as a connector:

  1. Open Settings > Connectors and click Add custom connector.
  2. Name: CPFHub.io. URL: https://api.cpfhub.io/mcp?api_key=YOUR_API_KEY.
  3. Save and enable the connector in the conversation.
⚠

The URL contains your key

With ?api_key= in the URL, the key is saved in the connector configuration. Do not share that URL or screenshots of the screen. If it leaks, generate a new key under API keys.

Claude Code (from the terminal):

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

Cursor (.cursor/mcp.json):

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

To test the connection and the key without spending credits, list the tools with curl:

bash
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"}'

The response should list the nine tools: lookup_cpf, lookup_cpf_realtime, lookup_cnpj, bulk_lookup_cpf, bulk_lookup_cnpj, get_bulk_job, create_kyc_link, get_kyc_link and get_quota_info.

Local: stdio through npx

Use it only when the MCP client does not support HTTP. The server runs on your machine, but each lookup calls the CPFHub.io API, so it needs internet access and an API key.

⚠

Limitations of the local package

The @cpfhub/mcp package has only lookup_cpf working. The get_quota_info tool does not work in the current version of the package (check your balance through GET /quota), and the other tools exist only on the remote server. Prefer the remote server whenever the client supports HTTP.

Claude Desktop or Cursor (through npx):

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

Environment variable (local)

bash
export CPFHUB_API_KEY=YOUR_API_KEY
npx @cpfhub/mcp
✦

Get your API key for free

Create an account at app.cpfhub.io and generate your key under API keys. The Free plan includes 50 credits per month.

Available tools

lookup_cpf

Simple Lookup: returns name, gender and date of birth from the CPFHub.io database (the same data as GET /cpf/{cpf}). It uses the cost of one Simple Lookup on your plan (1 credit by default) per CPF found. A CPF that is not found does not use a credit.

Parameters:

FieldTypeRequiredDescription
cpfstringYesCPF with or without formatting
api_keystringNoYour API key. Optional when the key was already sent on connection (x-api-key header or ?api_key=)

Response (the tool's text content, as JSON):

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
  }
}

On error, the tool returns isError: true and error as a string (the API replies in Portuguese, so the message below means "CPF not found in the database"):

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

When the per-minute request limit is reached, the error comes with retry_after (seconds to wait). The message below means "Per-minute request limit exceeded. Try again in 12 seconds.":

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

lookup_cpf_realtime

Real-Time Lookup: queries Receita Federal (Brazil's federal tax authority) at the time of the call and returns name, date of birth, year of death, registration status, control code and proof (the same data as POST /cpf/realtime). It uses 1.5 credits per successful lookup by default. Check your plan's cost in the dashboard. Remote server only.

Parameters:

FieldTypeRequiredDescription
cpfstringYesCPF with or without formatting
birth_datestringYesThe holder's date of birth, DD/MM/YYYY or DDMMYYYY
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

JSON
{
  "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 is always in the response as an integer or null. It is null when no death is on record or when the value received is invalid: it must have 4 digits, be between 1900 and the current year and not be earlier than the year of birth.

Errors follow the same format as lookup_cpf (isError: true, error as a string), with the messages of POST /cpf/realtime. A mismatched date of birth and Receita Federal unavailability do not use a credit.

lookup_cnpj

CNPJ lookup: legal name, tax status, address, CNAEs and partners (same data as GET /cnpj/{cnpj}). Uses one Simple Lookup from your plan (1 credit by default) per CNPJ found. An invalid or unknown CNPJ uses no credits.

Parameters:

FieldTypeRequiredDescription
cnpjstringYesCNPJ with or without formatting, numeric or alphanumeric
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

JSON
{
  "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" }
    ]
  }
}

The full response has the same fields as GET /cnpj/{cnpj}.

bulk_lookup_cpf

Creates a CPF batch (same behaviour as POST /cpf/bulk) and replies right away with the jobId. Up to 10,000 CPFs per batch; invalid and duplicate entries are dropped. Requires balance for every valid CPF, but only charges a Simple Lookup for each CPF found. Unknown, invalid and duplicate CPFs use no credits.

Parameters:

FieldTypeRequiredDescription
cpfsstring[]YesList of CPFs, with or without formatting
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

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

Then call get_bulk_job with the jobId to follow the batch.

bulk_lookup_cnpj

Creates a CNPJ batch (same behaviour as POST /cnpj/bulk). Same limits, response and credit rules as bulk_lookup_cpf.

Parameters:

FieldTypeRequiredDescription
cnpjsstring[]YesList of CNPJs, with or without formatting
api_keystringNoYour API key. Optional when the key was already sent on connection

get_bulk_job

Status and results of a batch (same data as GET /cpf/bulk/{jobId} and GET /cnpj/bulk/{jobId}). Call it again until status is done or failed; partial results already show up while processing. In a CNPJ batch the list comes in cnpjs, as {cnpj, found, data}. Uses no credits.

Parameters:

FieldTypeRequiredDescription
type"cpf" | "cnpj"YesBatch type
job_idstringYesThe jobId returned when the batch was created
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

JSON
{
  "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 }
    ]
  }
}

Creates an identity verification link (same behaviour as POST /kyc/links). Send the url to the person: they take a selfie with liveness and photograph their document. Creating the link uses no credits; each completed verification uses your plan's Identity Verification price (5 credits by default), approved or not.

Parameters:

FieldTypeRequiredDescription
external_idstringNoYour customer identifier, returned in the status and the webhook
redirect_urlstringNohttps URL the person returns to when done
expires_in_minutesnumberNoLink lifetime, 5 to 10,080 (default 1,440)
max_attemptsnumberNoAllowed attempts, 1 to 10 (default 3)
language"pt-BR" | "en" | "es"NoFlow language
cpfstringNoExpected CPF, cross-checked with the document
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

JSON
{
  "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"
  }
}

Status and decision of a link (same data as GET /kyc/links/{id}). Link status: pending, completed, canceled or expired; verification.status: approved, rejected or manual_review. Returns no personal data and uses no credits.

Parameters:

FieldTypeRequiredDescription
idstringYesThe id returned by create_kyc_link
api_keystringNoYour API key. Optional when the key was already sent on connection

Response:

JSON
{
  "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

Returns the plan, the remaining and used credits, the billing status and the account identifiers. It does not use a credit and works even with a zero balance.

Response:

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

billingStatus shows plan eligibility: active when the account has a subscription that gives access to the plan, including a subscription on the Free plan and statuses such as past_due. free when there is no valid subscription, for example canceled, unpaid or incomplete_expired. In that case, plan can come back as unknown. The default costs are 1 credit per Simple Lookup and 1.5 credits per Real-Time Lookup. The costs and overage rules specific to your plan are in the dashboard. The default limits are 30/min on the Simple Lookup (each batch submission counts as 1) and 5/min on the Real-Time Lookup. Custom plans can have different limits, so confirm with CPFHub.io support. Above the limit, the API replies 429 with the Retry-After header.

Also available through REST: GET /quota, with the same payload.

Tool definition (for manual use)

If you want to use the tool in system prompts without the MCP server:

JSON
{
  "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"]
  }
}

Example of use in Claude

With the MCP server configured, you can simply ask Claude:

"Validate CPF 123.456.789-09 and tell me the holder's name and date of birth."

Claude will automatically call lookup_cpf and include the data in its answer.

Repository


Updated on October 28, 2026