Geo-habilitación: ArcGIS en Ecosistemas Agénticos (Implementación con Claude y MCP)

CUE Ecuador 2026 — Quito, 27-28 de Agosto

Este repositorio contiene la implementación oficial presentada en la Conferencia de Usuarios Esri (CUE) Ecuador 2026. Demuestra cómo el estándar abierto Model Context Protocol (MCP) desarrollado por Anthropic puede geo-habilitar modelos de lenguaje fundacionales (LLMs), como Claude 3.5 Sonnet, conectándolos directamente con datos geográficos autorizados de ArcGIS Online y ArcGIS Enterprise de forma segura, determinista y en tiempo real.

---

2. Descripción del Proyecto

Uno de los principales desafíos en la Inteligencia Artificial Geográfica (GeoIA) es la desconexión existente entre las capacidades de razonamiento lingüístico de los LLMs y la naturaleza estructurada y espacial de los Sistemas de Información Geográfica (SIG). Tradicionalmente, resolver una pregunta espacial como "¿qué puntos de minería ilegal se encuentran cerca de esta concesión minera registrada, y cómo se ve eso en un mapa?" requería que un analista GIS:

1. Conectara con el portal y buscara el Feature Service correspondiente.
2. Escribiera una consulta espacial SQL y construyera filtros geométricos complejos.
3. Abriera un visor web o herramienta de escritorio para ajustar simbología y etiquetado.
4. Generara y exportara el plano en PDF o imagen para presentarlo.

Este agente de IA colapsa dicho ciclo de horas a segundos. Al actuar como un puente semántico mediante el protocolo MCP, permite que Claude interactúe de forma autónoma con los endpoints de la API REST de ArcGIS Online, encadenando herramientas de consulta, cruzando geometrías en caliente y solicitando la generación automática de mapas estáticos con simbología real basada en Web Maps. El LLM actúa como el orquestador ejecutivo, abstrayendo la plomería técnica de GIS y entregando reportes listos para la toma de decisiones.

---

3. Tech Stack (Arquitectura Tecnológica)

El ecosistema técnico de este agente está compuesto por las siguientes capas:

• Cliente de IA (Host MCP): Claude Desktop u orquestadores basados en Python (LangChain/LlamaIndex) encargados de ejecutar el loop de agente con el modelo Claude 3.5 Sonnet.
• Transporte y Protocolo: Estándar Model Context Protocol (MCP) sobre protocolo STDIO (entrada/salida estándar para ejecuciones locales) o HTTP con SSE (para despliegues distribuidos).
• Servidor MCP: Implementación en Python utilizando el framework FastMCP para la auto-exposición de herramientas.
• Integración GIS: ArcGIS API for Python (v2.3.0+) para el consumo directo de servicios REST de Esri sin dependencias de ArcPy o software de escritorio.
• Seguridad y Middleware: Starlette ASGI Middleware con autenticación basada en Bearer Token para proteger transportes de red HTTP.

---

4. Guía de Inicio Rápido

Sigue estos pasos para desplegar el servidor localmente y conectarlo con Claude Desktop antes de las demostraciones.

4.1 Clonar el Repositorio e Instalar Dependencias

Asegúrate de contar con Python 3.10 o superior instalado.

# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/arcgis-agentic-mcp.git
cd arcgis-agentic-mcp

# 2. Crear y activar el entorno virtual
python -m venv .venv
source .venv/Scripts/activate  # En Windows usa: .venv\Scripts\activate

# 3. Instalar dependencias requeridas
pip install -r requirements.txt

4.2 Configuración de Variables de Entorno

Copia la plantilla de configuración e ingresa tus credenciales autorizadas del portal de ArcGIS (Online o Enterprise):

cp .env.template .env

Edita el archivo .env resultante:

# URL de tu organización en ArcGIS Online o Portal Enterprise de Esri
AGOL_PORTAL_URL=https://tu-organizacion.maps.arcgis.com

# Credenciales del usuario con privilegios de consulta y edición (si aplica)
AGOL_USERNAME=tu_usuario_arcgis
AGOL_PASSWORD=tu_contrasena_segura

# Opcional: Autenticación alternativa con API Key de ArcGIS Location Platform
# AGOL_API_KEY=tu_arcgis_api_key_aqui

# Habilitar o deshabilitar herramientas de escritura (actualización de atributos)
ENABLE_EDITS=false

# Token secreto para proteger el endpoint HTTP en despliegues distribuidos
SECRET_TOKEN=token_secreto_generado_mcp

4.3 Configuración en Claude Desktop

Para que Claude Desktop cargue las herramientas de ArcGIS, edita el archivo de configuración global claude_desktop_config.json.

• Ruta en Windows: %APPDATA%\Claude\claude_desktop_config.json
• Ruta en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Agrega el servidor MCP apuntando a la ruta absoluta de tu entorno virtual y tu script server.py:

{
  "mcpServers": {
    "arcgis-online-mcp": {
      "command": "C:\\Users\\tu-usuario\\AppData\\Local\\Programs\\Python\\Python310\\python.exe",
      "args": [
        "D:\\DATA\\Proyectos Pro\\ArcGIS Online MCP Server Local\\server.py"
      ],
      "env": {
        "// Nota": "Puedes pasar variables directamente aquí o usar el archivo .env del proyecto",
        "AGOL_PORTAL_URL": "https://rn-esri-co.maps.arcgis.com",
        "ENABLE_EDITS": "false"
      }
    }
  }
}

Nota: Reinicia completamente la aplicación de Claude Desktop tras guardar los cambios.

---

5. Arquitectura y Flujo de Datos

5.1 Diagrama de Secuencia de Transporte (Mermaid.js)

El flujo de información entre el usuario, el cliente de IA y el portal GIS en Ecuador sigue la especificación estándar del protocolo MCP:

sequenceDiagram
    autonumber
    actor U as Usuario (CUE 2026 Quito)
    participant Host as Claude Desktop (Host LLM)
    participant Client as MCP Client (JSON-RPC)
    participant Server as Servidor MCP (Python FastMCP)
    participant AGOL as ArcGIS Online / REST API

    U->>Host: Solicita análisis en Quito
    Note over Host: El LLM identifica que requiere<br/>habilidades geográficas (Tools)
    Host->>Client: Invoca herramienta espacial
    Client->>Server: JSON-RPC (STDIO pipe o HTTP SSE)
    activate Server
    Server->>AGOL: HTTPS Request (ArcGIS Python API)
    AGOL-->>Server: Datos crudos / Extent (Esri JSON)
    Server->>Server: Enriquecimiento semántico (dpa_geografia.py)
    Server-->>Client: Respuesta JSON-RPC simplificada (Texto + Base64)
    deactivate Server
    Client-->>Host: Contexto mapeado en tokens óptimos
    Note over Host: El LLM asimila los resultados<br/>y genera el entregable visual
    Host-->>U: Mapa temático + Reporte Ejecutivo

5.2 Esquemas de Herramientas Clave (Tools JSON Schema)

El servidor MCP autogenera y expone esquemas a Claude. A continuación se detallan las dos firmas más representativas:

A. consulta_espacial_por_feature

Realiza un cruce espacial en caliente utilizando la geometría de un feature existente (ej. una concesión minera o zona de vulnerabilidad) como filtro espacial de proximidad sobre otra capa.

{
  "name": "consulta_espacial_por_feature",
  "description": "Usa la geometría de un feature de origen para buscar features en una capa destino que intersecten o estén en un radio de proximidad.",
  "input_schema": {
    "type": "object",
    "properties": {
      "source_layer_idx": {
        "type": "integer",
        "description": "Índice de la capa origen (ej: 9 para Catastro Minero)"
      },
      "source_where": {
        "type": "string",
        "description": "Cláusula SQL para filtrar el feature origen (ej: nam = 'San Antonio')"
      },
      "target_layer_idx": {
        "type": "integer",
        "description": "Índice de la capa destino a consultar (ej: 6 para Puntos de Conflicto)"
      },
      "distance": {
        "type": "number",
        "description": "Distancia del buffer de proximidad (opcional)"
      },
      "units": {
        "type": "string",
        "enum": ["esriSRUnit_Meter", "esriSRUnit_Kilometer"],
        "description": "Unidades de distancia del buffer"
      }
    },
    "required": ["source_layer_idx", "source_where", "target_layer_idx"]
  }
}

B. generar_mapa

Orquesta el servicio de impresión nativo de Esri (Export Web Map Task) para generar un documento PDF o imagen de alta calidad, calculando el encuadre óptimo del mapa a partir de un feature foco.

{
  "name": "generar_mapa",
  "description": "Genera y exporta un documento cartográfico multi-capa a disco, retornando la ruta y la imagen en base64 para previsualización.",
  "input_schema": {
    "type": "object",
    "properties": {
      "tema": {
        "type": "string",
        "enum": ["mineria_legal", "riesgo_ambiental", "conflicto_social", "mineria_ilegal"],
        "description": "Tema que define qué capas pre-configuradas activar automáticamente"
      },
      "focus_layer_idx": {
        "type": "integer",
        "description": "ID de la capa que guiará el encuadre (extent) del mapa"
      },
      "focus_where": {
        "type": "string",
        "description": "Filtro SQL para localizar el feature foco (ej: OBJECTID_1 = 15)"
      },
      "webmap_item_id": {
        "type": "string",
        "description": "ID del Web Map en ArcGIS Online del cual heredar simbología, renderers y etiquetas"
      },
      "basemap": {
        "type": "string",
        "default": "topo-vector",
        "description": "Mapa base a utilizar (satellite, topo-vector, gray, etc.)"
      },
      "format": {
        "type": "string",
        "default": "PNG32",
        "description": "Formato de salida del mapa (PNG32, PDF, JPG)"
      }
    },
    "required": []
  }
}

---

6. Casos de Uso Prácticos (Demos en Vivo - CUE Ecuador 2026)

Prueba el poder del agente copiando y pegando los siguientes prompts diseñados para el set de datos del catastro de recursos de Ecuador y ejecutados durante la sesión plenaria en el JW Marriott de Quito:

ID	Tipo de Análisis	Prompt de Prueba para Claude Desktop
Demo 1	Cruce de Proximidad e Impacto	"¿Qué puntos de minería no registrada o ilegal se encuentran a menos de 5 km de la concesión minera llamada 'TRAMITE 1'? Haz la consulta espacial y genera un mapa de la zona con fondo satelital heredando la simbología del Web Map oficial."
Demo 2	Análisis de Vulnerabilidad y Conflicto	"Revisa si existe algún título minero en fase 'INSCRITA' que intersecte con territorios de comunidades indígenas de la capa 13 en la provincia de Imbabura. Dame el reporte y crea el plano temático correspondiente en PDF."
Demo 3	Estadística y Mapeo Temático	"Genera una estadística agregada de las hectáreas concesionadas activas en la provincia de Zamora Chinchipe (usa el campo st_area_sh). Muestra las 3 más grandes y genera un mapa de calor/temático usando el tema 'riesgo_ambiental'."

---

7. Licencia y Atribución

Este proyecto se distribuye bajo la Licencia MIT.
Presentado por el equipo de GeoIA y Soluciones Agénticas de Esri Ecuador en la Conferencia de Usuarios Esri 2026. Para soporte técnico, abre un Issue en este repositorio o contacta a los expositores en el stand de Innovación Geoespacial.