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) directly 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 lookup_cpf, lookup_cpf_realtime and get_quota_info and get the data directly in its answer.

Installation

Use the remote server (https://api.cpfhub.io/mcp), which needs no installation and has all three tools. 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).

Remote: Streamable HTTP (recommended)

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.

Claude Code (from the 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": "YOUR_API_KEY" }
    }
  }
}

To test the connection and the key without spending credits, list the tools with 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"}'

The response should list lookup_cpf, lookup_cpf_realtime 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.

Claude Desktop or Cursor (through npx):

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

Environment variable (local)

export CPFHUB_API_KEY=YOUR_API_KEY
npx @cpfhub/mcp

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:

Response (the tool's text content, as 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"):

{
  "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.":

{
  "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. The typical time is about 1 second (not an SLA). Remote server only.

Parameters:

Response:

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

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:

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

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

• github.com/cpfhub/cpfhub-mcp: source code and issues for the local package
• npm: @cpfhub/mcp: versions of the local package

Updated on October 4, 2026