Inicio / Artículos / Conectar agentes de IA a GeoServer 2.28 con la extensión MCP

geoservermcpai-agentsgislangchain

Conectar agentes de IA a GeoServer 2.28 con la extensión MCP

Instala el JAR de la extensión GeoServer MCP, comprueba que se ha cargado, llama al endpoint con curl, conecta Claude Desktop o LangChain y protege el acceso y las herramientas de escritura.

1377 palabras

Dale a tus agentes de IA una vista en vivo de GeoServer

Basta con una extensión y un reinicio para que un agente consulte tu catálogo por MCP. Sin sidecar en Python ni contenedores Docker de más. Estas notas cubren la versión 0.1.0 de GeoServer MCP Extension y GeoServer 2.28.x. Se distribuye como un JAR en pre-release de GitHub y no sustituye al paquete geoserver-mcp de PyPI.

Qué hace la extensión

Es un plugin de GeoServer como cualquier otro. Cuando el JAR está dentro de GeoServer y el servidor se ha reiniciado, el propio GeoServer habla MCP en esta dirección:

http://127.0.0.1:8080/geoserver/mcp

Los agentes envían JSON-RPC sobre HTTP (Streamable HTTP) y GeoServer responde desde su propio catálogo. Los resultados siguen pasando por las reglas de seguridad de GeoServer.

Los nombres de las herramientas de catálogo (list, get, query, create, delete, publish) son los mismos que usa el servidor MCP en Python. Los extras administrativos del paquete de Python (gestión de usuarios, reload, subida de archivos) no vienen incluidos, y eso vuelve a salir más abajo, en los errores habituales.

Las herramientas de escritura están activadas por defecto. Si quieres un endpoint de solo lectura, añade mcp.allowWrites=false a la configuración del directorio de datos.

En Windows, escribe 127.0.0.1 en lugar de localhost. Algunos clientes MCP en Python convierten localhost en la dirección IPv6 ::1 y reciben un HTTP 503, aunque la ruta IPv4 funcione bien.

Requisitos

  • GeoServer 2.28.x sobre Java 17 o 21
  • Un usuario de GeoServer (una instalación nueva trae admin / geoserver)
  • El JAR de la extensión, del que hablamos a continuación

No pongas este JAR en GeoServer 2.20.x ni 3.x. La versión 2.20 funciona con Java 11, no arranca y devuelve HTTP 503. GeoServer 3 pasó a Jakarta Servlet y esta compilación no se carga ahí. Si todavía necesitas un GeoServer antiguo para otras tareas, déjalo tal cual y monta una instalación 2.28 aparte para el plugin.

Cómo conseguir el JAR

El archivo que necesitas es gs-mcp-0.1.0.jar, publicado como release de GitHub, el enlace de descarga es https://download.gis-mcp.com/geoserver-mcp-extension y guárdalo en algún sitio a mano, como la carpeta de Descargas. También puedes compilarlo o descargarlo del repositorio https://github.com/mahdin75/geoserver-mcp.

Instalación

  1. Abre GeoServer y entra en About & Status y luego en About GeoServer. La versión tiene que empezar por 2.28.
  2. Detén GeoServer.
  3. Copia gs-mcp-0.1.0.jar en la carpeta WEB-INF/lib de la aplicación web. En el paquete binario/Jetty es <GEOSERVER_ROOT>/webapps/geoserver/WEB-INF/lib, y en Tomcat, <CATALINA_BASE>/webapps/geoserver/WEB-INF/lib.

En Windows, la ruta final suele quedar así:

D:\geoserver-2.28.5\webapps\geoserver\WEB-INF\lib\gs-mcp-0.1.0.jar

Después vuelve a arrancar el servidor:

Start GeoServer.

No hay que editar ningún web.xml: GeoServer detecta el plugin por sí solo.

Comprobar que se ha cargado

  1. Abre http://127.0.0.1:8080/geoserver/web/ e inicia sesión.
  2. Ve a About & Status y luego a Modules.
  3. Busca GeoServer MCP Extension (gs-mcp).

Si después de copiarlo la propia interfaz web devuelve 503, el JAR ha ido a parar al GeoServer equivocado. Quítalo, reinicia e instálalo en una instancia 2.28.x.

Llamar al endpoint

El plugin vive en /mcp dentro de la aplicación web de GeoServer, así que para un GeoServer montado en /geoserver la URL pública es /geoserver/mcp. De serie hace falta iniciar sesión, con HTTP Basic y un usuario real de GeoServer. En Windows PowerShell, usa curl.exe, porque curl a secas es otro comando.

Initialize

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Listar las herramientas

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}" \
  http://127.0.0.1:8080/geoserver/mcp

La respuesta debería traer unas 30 herramientas de catálogo, por ejemplo list_workspaces, list_layers, create_workspace y query_features.

Listar capas

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"list_layers\",\"arguments\":{}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Tres comprobaciones rápidas:

  • Un POST con -u admin:geoserver devuelve un resultado JSON.
  • Un POST sin usuario devuelve HTTP 401.
  • Un GET a /geoserver/mcp devuelve HTTP 405.

Conectar un cliente de IA

Al cliente le basta con poder enviar JSON por POST a una URL. Claude Desktop y LangChain no vienen integrados en el plugin, así que lo único que haces es apuntar el cliente a GeoServer.

Claude Desktop

Los servidores MCP locales se comunican con Claude Desktop por stdio, pero este plugin es un servicio HTTP. Un pequeño puente llamado mcp-remote une ambos mundos, y necesita Node.js para que exista npx.

  1. Abre Settings, luego Developer y luego Edit Config, que abre claude_desktop_config.json. En Windows está en %APPDATA%\Claude\claude_desktop_config.json, y en macOS, en ~/Library/Application Support/Claude/claude_desktop_config.json.
  2. Añade el servidor de abajo y conserva las entradas de mcpServers que ya tengas:
{
  "mcpServers": {
    "geoserver": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/geoserver/mcp",
        "--allow-http",
        "--header",
        "Authorization:Basic YWRtaW46Z2Vvc2VydmVy"
      ]
    }
  }
}

YWRtaW46Z2Vvc2VydmVy es admin:geoserver en Base64, así que cámbialo si tu contraseña no es la predeterminada. El flag --allow-http hace falta porque un GeoServer local usa HTTP plano y no HTTPS.

  1. Cierra Claude Desktop por completo y vuelve a abrirlo.
  2. Pruébalo con un prompt como «¿Qué workspaces hay en este GeoServer?» o «Crea un workspace llamado demo_mcp y luego enséñame las capas de topp».

Si las herramientas no aparecen, comprueba primero que el servidor está levantado y que el POST con curl de antes funciona con -u admin:geoserver.

LangChain

Empieza por el import:

from langchain_mcp_adapters.client import MultiServerMCPClient

Después crea el cliente:

client = MultiServerMCPClient(
    {
        "geoserver": {
            "transport": "streamable_http",
            "url": "http://127.0.0.1:8080/geoserver/mcp",
            "headers": {"Authorization": "Basic YWRtaW46Z2Vvc2VydmVy"},
        }
    }
)
tools = await client.get_tools()

Si streamable_http da error, prueba con "transport": "http". La URL y la cabecera Basic no cambian.

El proyecto incluye un smoke test en extension/examples/langchain_mcp_test.py:

pip install -r extension/examples/requirements-langchain.txt
python extension/examples/langchain_mcp_test.py --url http://127.0.0.1:8080/geoserver/mcp

El script tiene una opción --agent que, además, ejecuta un agente de LangChain a través de OpenRouter, y para eso debe estar definida OPENROUTER_API_KEY. Necesita Python 3.10.11 o posterior (3.11+ también vale). Las primeras compilaciones de 3.10.0 suelen fallar en TLS al conectarse a OpenRouter.

Cerrar la puerta a los usuarios anónimos

La autenticación está activada por defecto. Puedes ajustarla con un archivo opcional mcp.properties en el directorio de datos de GeoServer:

mcp.enabled=true
mcp.path=/mcp
mcp.requireAuthentication=true
mcp.allowWrites=true
mcp.maxFeatures=100

Con mcp.requireAuthentication=true, una petición sin credenciales recibe HTTP 401, y una con usuario de GeoServer ejecuta las herramientas. Ese usuario sigue viendo y modificando solo lo que permita la seguridad de datos de GeoServer.

Déjalo en true salvo que los clientes anónimos de verdad deban llegar a objetos públicos del catálogo. Con mcp.allowWrites=false, las herramientas de escritura desaparecen de tools/list y se rechazan en tools/call. Tras cualquier cambio en mcp.properties, reinicia GeoServer.

Errores en los que tropieza la gente

  • Serie de GeoServer equivocada. Este JAR solo funciona en 2.28.x, y con 2.20.x la aplicación web no arranca.
  • Java equivocado. GeoServer 2.28 necesita Java 17 o 21, y con Java 11 el plugin no se carga.
  • No reiniciar después de copiar el JAR.
  • Falta la cabecera Authorization. Con la configuración por defecto, la respuesta es 401.
  • Usar localhost en Windows. Los clientes MCP en Python pueden ir por IPv6 y toparse con un 503, así que usa http://127.0.0.1:8080/geoserver/mcp.
  • Un workspace llamado mcp. Elige otro nombre, porque puede chocar con la ruta /mcp.
  • Esperar herramientas administrativas. Subida de shapefiles, vistas SQL, reloads y gestión de usuarios no existen en este plugin.
  • Errores TLS con --agent. En Python 3.10.0 la parte de GeoServer del smoke test puede pasar mientras la llamada a OpenRouter se cae, así que pasa a 3.10.11 o 3.11+.

Dónde está el código

El código fuente está en https://github.com/mahdin75/geoserver-mcp (mira la carpeta extension). La compilación 0.1.0 tiene su propia página de release, https://github.com/mahdin75/geoserver-mcp/releases/tag/extension-v0.1.0, y ese mismo repositorio acepta issues y pull requests.

Resumiendo el ciclo: descarga el JAR, ponlo en WEB-INF/lib de una instalación 2.28, reinicia y envía POST a /geoserver/mcp con credenciales válidas de GeoServer.

Todos los artículosEnviar el brief