Conecta tu agente o tu sistema

Inicio rápido

1. Pide tu llave. El plan Gratis trae 1.500 créditos al mes. Guárdala como un secreto, nunca en el código.
2. Haz la primera consulta. El código DIVIPOLA de un municipio por su nombre cuesta 1 crédito:

export TERRNOVA_LLAVE=rt_live_...
curl -s -X POST https://terrnova.com/v1/co/territorio/dane_divipola_buscar \
  -H "Authorization: Bearer $TERRNOVA_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Cali"}'

La respuesta trae "estado":"encontrado", los municipios que coinciden en datos.elementos y la fuente (DANE) con su licencia en procedencia. La búsqueda respeta las tildes: «Bogota» no encuentra «Bogotá».

3. Mira tu saldo con GET /v1/uso.

MCP

La puerta habla MCP por streamable HTTP, con la llave en la cabecera Authorization.

Claude Code:

claude mcp add --transport http terrnova https://terrnova.com/mcp \
  --header "Authorization: Bearer $TERRNOVA_LLAVE"

Cursor y otros clientes que aceptan url y headers:

{
  "mcpServers": {
    "terrnova": {
      "url": "https://terrnova.com/mcp/territorio",
      "headers": { "Authorization": "Bearer rt_live_..." }
    }
  }
}

Claude Desktop y otros clientes que solo hablan por stdio, con el puente mcp-remote:

{
  "mcpServers": {
    "terrnova": {
      "command": "npx",
      "args": ["mcp-remote", "https://terrnova.com/mcp/ambiente",
               "--header", "Authorization:${TERRNOVA_AUTH}"],
      "env": { "TERRNOVA_AUTH": "Bearer rt_live_..." }
    }
  }
}

Perfiles

Ruta	Qué expone	Para
/mcp	Las 205 herramientas, más ficha_lugar y fuente_describir	Clientes que buscan herramientas por su cuenta, como Claude
/mcp/<familia>	Las de una sola familia	Un caso de uso de un solo tema: lo más preciso y lo más rápido
/mcp/catalogo	Pocas herramientas genéricas que buscan en el catálogo	Clientes con tope de herramientas, como los modelos de OpenAI (128)

Familias: ambiente, contratacion, empresas, estadisticas, justicia, normativa, territorio. Todos los perfiles traen las herramientas de nombre a código (1 crédito) y fuente_describir, que no gasta créditos.

API REST

Las herramientas siguen el patrón POST /v1/co/<familia>/<herramienta>, con la entrada en JSON. La ficha de un lugar está en POST /v1/fichas. El esquema completo, con la entrada de cada herramienta, está en /openapi.json y se navega en /docs.

Para	Dónde
Lista de herramientas con su costo	GET /v1/herramientas
Ficha técnica de una fuente	GET /v1/fuentes/{fuente_id}
Saldo del mes	GET /v1/uso
Estado por fuente	GET /v1/estado

Las rutas de catálogo son públicas y no gastan créditos.

Contrato rt/1

Toda consulta que llega a la fuente devuelve el mismo sobre:

Campo	Contenido
estado	encontrado, no_encontrado, fuera_de_cobertura o parcial
datos	El resultado
huella	sha256 de datos, para verificar que no cambió
procedencia	Por fuente: entidad, URL, norma (si la hay), licencia, atribución, servido_desde, consultado_en y completitud
avisos	Lo que debes saber: total desconocido, datos no recientes, copia vencida…
geo_result	Las geometrías, en EPSG:4326 (lon, lat)
creditos	Lo que costó esa consulta

«No encontrado» no es «no se pudo». Cuando la fuente no responde llega un error, nunca un sobre vacío. Terrnova nunca inventa un dato ni hace pasar uno viejo por actual: servido_desde: obsoleto siempre llega con aviso.

Errores

Por REST, en application/problem+json (RFC 9457), con un code estable y el solicitud_id que debes darnos si escribes a soporte.

Cada llave tiene una ráfaga de 20 consultas y repone 60 por minuto. Reintenta con espera creciente, nunca en bucle cerrado.

Recursos

• /llms.txt: el catálogo en texto para agentes.
• /.well-known/mcp/server-card.json: la tarjeta del servidor MCP.
• /estado: el estado de la puerta y de cada fuente según su canario diario.
• Soporte: soporte@terrnova.com, de lunes a viernes de 8:00 a 18:00, hora de Colombia, sin festivos.