Ir al contenido

Colonix en tu asistente de IA (MCP)

Si trabajas con un asistente de IA, puedes darle acceso a Colonix para que consulte códigos postales, colonias y claves del SAT mientras le pides cosas: revisar una dirección, armar el domicilio de una Carta Porte o ayudarte a programar la integración con respuestas reales. Se hace con un servidor MCP que corre en tu computadora, usa tu llave y solo lee.

MCP (Model Context Protocol) es el estándar con el que los asistentes usan herramientas externas. El servidor de Colonix es el paquete de npm @silgaru/colonix-mcp: cada herramienta es un endpoint de la API, con los mismos parámetros y los mismos planes. Además, el asistente tiene a la mano las guías de esta documentación y el significado de cada campo de las respuestas, para explicarte bien lo que recibe.

  • “¿Qué colonias tiene el código postal 06700?”
  • “¿La colonia Guerrero es del 06300? Dame las claves para el complemento Carta Porte.”
  • “Busca la colonia ‘Roma Nrte’ aunque esté mal escrita.”
  • “¿Qué decía el SAT del código postal 22000 el 1 de marzo de 2026?”
  • “¿Qué código postal corresponde a 19.4194, -99.1617?”
  1. Abre Configuración → Desarrollador → Editar configuración.

  2. Agrega el servidor a claude_desktop_config.json con tu llave:

    {
    "mcpServers": {
    "colonix": {
    "command": "npx",
    "args": ["-y", "@silgaru/colonix-mcp"],
    "env": { "COLONIX_API_KEY": "tu-llave" }
    }
    }
    }

    En Windows, si no encuentra npx, usa "command": "cmd" y "args": ["/c", "npx", "-y", "@silgaru/colonix-mcp"].

  3. Reinicia Claude Desktop.

Herramienta Endpoint Plan
get_postal_code Un código postal Todos (los bloques opcionales, desde Básico)
validate_postal_code_settlement Validar código postal y colonia Todos (sat y cfdi, desde Básico)
search_settlements Buscar asentamientos Todos
autocomplete_settlements Autocompletar Todos
list_postal_codes Listar códigos postales Todos
list_states, list_municipalities, list_municipality_settlements, list_settlement_types Estados, municipios, asentamientos de un municipio y tipos Todos
get_postal_code_history Historial de un código postal Todos (sat, desde Básico)
get_data_info Versión del dato Todos
get_sat_postal_code Datos del SAT de un código postal Desde Básico
reverse_geocode Código postal de un punto Desde Básico
find_nearby_postal_codes Códigos postales cercanos Desde Básico
batch_get_postal_codes Lote Negocio y Enterprise
list_changes Cambios Negocio y Enterprise
list_sat_discrepancies Diferencias SAT ↔ SEPOMEX Negocio y Enterprise
get_colonix_guide Ninguno: las guías de esta documentación y los campos de cada respuesta vienen en el paquete Todos, sin gastar consultas

Los códigos postales de demostración (06700, 44100, 64000, 22000 y 77500) muestran los datos del SAT, la ubicación y la zona metropolitana en todos los planes. Si tu plan no incluye algo, el asistente recibe el error plan-not-allowed y te lo dice.

Cada vez que el asistente usa una herramienta es una consulta de tu plan, igual que una llamada a la API (el lote cuenta una por código postal); get_colonix_guide no cuenta, porque no llama a la API. El asistente decide cuántas hace: si le pides algo grande, puede hacer varias. El servidor le indica no recorrer páginas para copiar el catálogo.

Las respuestas con error no cuentan. Por eso, si el asistente manda un código postal sin su cero (6700) o el nombre de un estado donde va su clave, el servidor deja que conteste la API, que dice cómo corregirlo (“Did you mean 06700?”), y le indica qué herramienta da la clave. En el lote no: ahí cada código cuenta aunque esté mal escrito, así que el servidor lo revisa antes de consultar.

  • Solo lectura: ninguna herramienta cambia nada en tu cuenta.
  • Tu llave solo viaja a colonix.silgaru.mx por HTTPS; el servidor no la escribe en ningún registro y no sigue redirecciones.
  • Sin dependencias: el paquete es solo su propio código, con licencia MIT, y no guarda nada en tu computadora.