Servidor MCP

CPFHub.io tiene un servidor Model Context Protocol remoto en https://api.cpfhub.io/mcp. Permite que agentes de IA como Claude, Cursor y otros clientes MCP consulten CPF (el número de identificación fiscal de personas físicas en Brasil) directamente durante la conversación, sin instalar nada.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo abierto que permite a los LLMs llamar herramientas externas de forma estándar. Con el servidor MCP de CPFHub.io, el agente puede llamar a lookup_cpf, lookup_cpf_realtime y get_quota_info y recibir los datos directamente en su respuesta.

Instalación

Usa el servidor remoto (https://api.cpfhub.io/mcp), que no requiere instalación y tiene las tres tools. El paquete local npx @cpfhub/mcp existe solo para clientes sin soporte HTTP y tiene limitaciones (ver abajo).

Configuración

CPFHub.io admite dos modos de conexión: remoto (recomendado, sin instalación) y local (mediante npx, alternativa para clientes sin soporte HTTP).

Remoto: HTTP Streamable (recomendado)

Funciona en cualquier cliente MCP que admita conexiones HTTP (Streamable HTTP). No requiere Node.js instalado. La clave de API va en el header x-api-key o, para clientes que no aceptan headers, en la URL como ?api_key=.

Claude Desktop y claude.ai: los servidores remotos no van en claude_desktop_config.json (ese archivo es solo para servidores locales). Agrégalo como conector:

1. Abre Configuración > Conectores y haz clic en Agregar conector personalizado.
2. Nombre: CPFHub.io. URL: https://api.cpfhub.io/mcp?api_key=TU_API_KEY.
3. Guarda y activa el conector en la conversación.

Claude Code (desde la 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": "TU_API_KEY" }
    }
  }
}

Para probar la conexión y la clave sin gastar créditos, lista las tools con 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"}'

La respuesta debe listar lookup_cpf, lookup_cpf_realtime y get_quota_info.

Local: stdio con npx

Úsalo solo cuando el cliente MCP no admita HTTP. El servidor corre en tu máquina, pero cada consulta llama a la API de CPFHub.io, así que necesita internet y una clave de API.

Claude Desktop o Cursor (mediante npx):

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

Variable de entorno (local)

export CPFHUB_API_KEY=TU_API_KEY
npx @cpfhub/mcp

Tools disponibles

lookup_cpf

Consulta Simple: devuelve nombre, género y fecha de nacimiento desde la base de datos de CPFHub.io (los mismos datos de GET /cpf/{cpf}). Consume el costo de una Consulta Simple de tu plan (1 crédito por defecto) por cada CPF encontrado. Un CPF no encontrado no consume crédito.

Parámetros:

Respuesta (contenido de texto de la tool, en 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
  }
}

En caso de error, la tool devuelve isError: true y error como string (la API responde en portugués, así que el mensaje de abajo significa "CPF no encontrado en la base de datos"):

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

Cuando se alcanza el límite de solicitudes por minuto, el error viene con retry_after (segundos de espera). El mensaje de abajo significa "Límite de solicitudes por minuto excedido. Inténtalo de nuevo en 12 segundos.":

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

lookup_cpf_realtime

Consulta en Tiempo Real: consulta la Receita Federal (la autoridad tributaria federal de Brasil) en el momento de la llamada y devuelve nombre, fecha de nacimiento, año de fallecimiento, situación de registro, código de control y comprobante (los mismos datos de POST /cpf/realtime). Consume 1,5 créditos por consulta exitosa por defecto. Consulta el costo de tu plan en el dashboard. El tiempo típico es de cerca de 1 segundo (no es un SLA). Solo en el servidor remoto.

Parámetros:

Respuesta:

{
  "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 siempre viene en la respuesta como entero o null. Es null cuando no hay fallecimiento registrado o cuando el valor recibido es inválido: debe tener 4 dígitos, estar entre 1900 y el año actual y no ser anterior al año de nacimiento.

Los errores siguen el mismo formato de lookup_cpf (isError: true, error como string), con los mensajes de POST /cpf/realtime. Una fecha de nacimiento que no coincide y la indisponibilidad de la Receita Federal no consumen crédito.

get_quota_info

Devuelve el plan, los créditos restantes y usados, el estado de facturación y los identificadores de la cuenta. No consume crédito y funciona incluso con el saldo en cero.

Respuesta:

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

billingStatus indica la elegibilidad al plan: active cuando la cuenta tiene una suscripción que da acceso al plan, incluida una suscripción en el plan Gratis y estados como past_due. free cuando no hay una suscripción válida, por ejemplo canceled, unpaid o incomplete_expired. En ese caso, plan puede venir como unknown. Los costos por defecto son 1 crédito por Consulta Simple y 1,5 créditos por Consulta en Tiempo Real. Los costos y las reglas de excedente específicas de tu plan están en el dashboard. Los límites por defecto son 30/min en la Consulta Simple (cada envío de lote cuenta como 1) y 5/min en la Consulta en Tiempo Real. Los planes personalizados pueden tener límites distintos, así que confirma con el soporte de CPFHub.io. Por encima del límite, la API responde 429 con el header Retry-After.

También disponible por REST: GET /quota, con el mismo payload.

Definición de la tool (para uso manual)

Si quieres usar la tool en prompts de sistema sin el 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"]
  }
}

Ejemplo de uso en Claude

Con el servidor MCP configurado, simplemente puedes pedirle a Claude:

"Valida el CPF 123.456.789-09 y dime el nombre y la fecha de nacimiento del titular."

Claude llamará automáticamente a lookup_cpf e incluirá los datos en su respuesta.

Repositorio

• github.com/cpfhub/cpfhub-mcp: código fuente e issues del paquete local
• npm: @cpfhub/mcp: versiones del paquete local

Actualizado el 4 de octubre de 2026