API y servidor MCP

Lleva la consulta urbanística y a Norma, la IA de Licencia.ai, a tus propias herramientas: scripts, tu ERP, hojas de cálculo o asistentes como Claude o Cursor. Disponible en el plan Custom.

1. Tu clave de API

Créala en el panel, en Mi cuenta → API. Se enseña una sola vez: guárdala como cualquier contraseña y, si se expone, revócala desde la misma página. Va en cada petición, en el encabezado:

Authorization: Bearer lic_…

Lo que hagas con la API cuenta en el consumo de tu plan como si lo hicieras en el panel: cada parcela nueva es una consulta (repetir una ya consultada no cuenta) y cada pregunta a Norma, una interacción. Las parcelas y las conversaciones quedan en tu cuenta. Cada clave admite 60 peticiones por minuto.

2. API REST

Base: https://licencia.ai/api/v1. Las respuestas son JSON.

Consulta urbanística por referencia catastral

El mismo informe que el panel: datos del Catastro, clasificación y calificación, parámetros del planeamiento, afecciones sectoriales, terreno, edificabilidad y el aprovechamiento orientativo. Parámetros opcionales para afinar la edificabilidad: ancho (de la calle, m), plantas y profundidad (m).

curl https://licencia.ai/api/v1/consulta/0829306EG1302N \
  -H "Authorization: Bearer $LICENCIA_API_KEY"

Devuelve rc, datosFecha (cuándo se obtuvieron los datos de las fuentes oficiales), informe (el análisis completo) y aprovechamiento.

Aprovechamiento y edificabilidad

Solo las cifras de aprovechamiento (techo máximo, ocupación, plantas, viviendas…) y la edificabilidad, del mismo análisis:

curl "https://licencia.ai/api/v1/aprovechamiento/0829306EG1302N?ancho=12" \
  -H "Authorization: Bearer $LICENCIA_API_KEY"

Preguntar a Norma

Norma consulta en vivo el Catastro, el planeamiento y la normativa técnica, y responde con las fuentes que ha leído. Puede tardar hasta un par de minutos. Para seguir la misma conversación, envía el conversacion de la respuesta anterior.

curl https://licencia.ai/api/v1/norma \
  -H "Authorization: Bearer $LICENCIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pregunta": "¿Qué superficie mínima debe tener una vivienda en Catalunya?"}'

{
  "respuesta": "Según el Decret 141/2012…",
  "fuentes": [
    {"tipo": "normativa", "fuente": "Decret 141/2012 — condicions mínimes d'habitabilitat…", "url": "https://…", "extracto": "…"}
  ],
  "conversacion": 1234
}

Comprobar la clave

curl https://licencia.ai/api/v1/yo -H "Authorization: Bearer $LICENCIA_API_KEY"

Errores

Los errores llevan {"error": "…", "tipo": "…"} con el texto en castellano:

3. Servidor MCP

Con el servidor MCP (Model Context Protocol), tu asistente puede usar a Norma como una herramienta más. Dirección: https://licencia.ai/mcp (transporte HTTP «streamable»), con la misma clave en el encabezado Authorization. Herramientas:

• consulta_urbanistica(referencia_catastral): el informe urbanístico de la parcela con su aprovechamiento.
• preguntar_a_norma(pregunta): la respuesta de Norma con sus fuentes.

Claude Code

claude mcp add --transport http norma https://licencia.ai/mcp \
  --header "Authorization: Bearer lic_…"

Claude Desktop

En Ajustes → Desarrollador → Editar configuración (claude_desktop_config.json), a través de mcp-remote (necesita Node.js):

{
  "mcpServers": {
    "norma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://licencia.ai/mcp",
               "--header", "Authorization:${LICENCIA_AUTH}"],
      "env": { "LICENCIA_AUTH": "Bearer lic_…" }
    }
  }
}

Cursor y otros clientes

Cualquier cliente que admita servidores MCP remotos con encabezados propios. En Cursor, en ~/.cursor/mcp.json:

{
  "mcpServers": {
    "norma": {
      "url": "https://licencia.ai/mcp",
      "headers": { "Authorization": "Bearer lic_…" }
    }
  }
}

Los conectores de claude.ai y de ChatGPT piden de momento autenticación OAuth, que aún no ofrecemos: úsalos a través de la API o de un cliente de los de arriba.

4. Buenas prácticas

• No pongas la clave en el código ni en repositorios: usa variables de entorno.
• Una clave por integración: así puedes revocar una sin tocar las demás.
• Los resultados son orientativos y llevan sus fuentes: verifícalos con el planeamiento oficial y el ayuntamiento antes de usarlos en un proyecto.