Servidor MCP

ogr-slip2d-mcp es el servidor oficial de Model Context Protocol (MCP) de OGR Slip2D. Con él, un agente de IA puede construir el modelo de un talud, ejecutar el análisis y leer y dibujar los resultados, ya sea en modelos propios del servidor o en el modelo abierto en la ventana del programa, donde el usuario ve cada edición y puede deshacerla. Esta página es la referencia técnica (opciones, transportes, las 74 herramientas, recursos y modelo de seguridad); cómo conectar un cliente concreto se explica en la página de IA.

5.1.1Qué es#

• Una capa ligera sobre la capa de operaciones. Cada herramienta equivale a una operación de ogr_api (73 operaciones), más server_info, que solo existe en el servidor. Las herramientas están escritas a mano, porque la descripción de una herramienta y los tipos de sus parámetros son toda la interfaz que ve un modelo de lenguaje; un test vigila que ambas capas se correspondan: cada operación tiene su herramienta, cada herramienta llama a una operación y cada parámetro de una herramienta es un parámetro de su operación. Las mismas operaciones se pueden llamar desde Python (Sección 5.3).
• El SDK oficial. El servidor se basa en el SDK de MCP para Python (mcp ≥ 2.1 y < 3, licencia MIT), que se instala con el extra [mcp]. El programa de escritorio no lo necesita.
• Dos transportes. Entrada/salida estándar (el transporte por defecto) y HTTP en continuo (Streamable HTTP), con token de portador y, para los clientes que llegan al servidor por Internet, OAuth 2.1.
• Unidades del SI siempre (m, kN, kPa, kN/m³, grados), con x hacia la derecha e y hacia arriba, sea cual sea el sistema de unidades que muestre la ventana.
• Los análisis son tareas. Un análisis se ejecuta en un proceso hijo que se puede cancelar; cada edición de un modelo es un paso de deshacer.
• Prioridad a la ventana abierta. Si OGR Slip2D está abierto, las llamadas actúan sobre su ventana (Sección 5.1.6).

5.1.2Instalación#

Desde un clon del repositorio, con Python 3.11 o posterior:

pip install -e ".[mcp]"
ogr-slip2d-mcp --version        # ogr-slip2d-mcp 0.1.235, on standard error
python -m ogr_mcp --version     # the same program, if the command is not on PATH

Sin el SDK, el servidor se detiene con el código de salida 3 y pide que se instale el extra (pip install "ogr-slip2d[mcp]"). ogr-slip2d-mcp --help enumera todas las opciones. Los archivos de configuración de los clientes (aplicaciones de chat de escritorio, modelos locales y clientes HTTP) están en la página de IA.

5.1.3Opciones de la línea de comandos#

No se escribe nada en la salida estándar, porque con stdio ese flujo transporta el protocolo. Los mensajes van a la salida de error estándar o a --log-file.

5.1.4Transportes#

Entrada/salida estándar#

El cliente arranca el servidor como proceso hijo y se comunica con él mediante sus flujos estándar; no se abre ningún puerto. Es el transporte de las aplicaciones de chat de escritorio, los agentes de programación y los clientes de modelos locales.

ogr-slip2d-mcp --workdir "C:\models"
ogr-slip2d-mcp --profile compact --workdir "C:\models"     # small local models

HTTP en continuo (Streamable HTTP)#

Con --transport http, el servidor responde en http://HOST:PORT/mcp, sin estado y con respuestas JSON. Cada petición necesita Authorization: Bearer <token>; si el token falta o es incorrecto, se responde con 401. El token se toma de --token, --token-file u OGR_MCP_TOKEN, por ese orden. Si no se indica ninguno en un host de bucle local, el servidor genera uno (de 43 caracteres) y lo escribe en la salida de error estándar al arrancar.

ogr-slip2d-mcp --transport http --port 8765 --token-file token.txt --workdir "C:\models"

Las cabeceras Host y Origin se comprueban aunque el token sea correcto: si el Host no es el de este servidor, se responde con 421, y si el Origin es ajeno, con 403. Los hosts permitidos son 127.0.0.1, localhost, [::1] y el valor de --host, en el puerto indicado; los orígenes permitidos son 127.0.0.1 y localhost en ese puerto, más cada --allow-origin. Con --tls-cert y --tls-key, el mismo punto de acceso se sirve por HTTPS.

OAuth 2.1 para clientes en Internet#

Algunos clientes alojados solo se conectan a un servidor HTTPS público y solo mediante OAuth. Para ellos, el servidor sigue escuchando en 127.0.0.1, se coloca delante un túnel o un proxy inverso que termina HTTPS y se comunica al servidor su dirección pública con --public-url. El servidor actúa entonces como su propio servidor de autorización OAuth 2.1: PKCE con S256, registro dinámico de clientes y tokens vinculados al recurso <public-url>/mcp. El acceso se concede escribiendo el token del servidor en su página <public-url>/approve; se considera propietario a quien conoce el token. El token estático sigue funcionando como cabecera de portador para los clientes que pueden enviarla. Los límites se enumeran en la Sección 5.1.11.

ogr-slip2d-mcp --transport http --port 8765 --token-file token.txt \
               --public-url https://your-tunnel.example --workdir "C:\models"

5.1.5Perfiles y conjuntos de herramientas#

Un modelo local pequeño se pierde entre muchas herramientas, y la descripción de cada herramienta consume contexto en cada petición. Por eso el servidor ofrece dos perfiles:

• full (por defecto): las 74 herramientas.
• compact: las 14 herramientas que bastan para un ciclo completo de construcción, cálculo y lectura: server_info, catalog, project_new, project_open, project_save, project_summary, model_define, analysis_configure, analysis_run, job_get, job_cancel, results_get, model_render y python_exec. model_define construye toda la geometría en una sola llamada y python_exec cubre el resto. Están marcadas con C en las tablas de la Sección 5.1.7.

--toolsets sustituye el perfil por una lista de conjuntos de herramientas: core (10 herramientas), model (9), settings (3), analysis (7), loads (5), supports (6), search (5), annotations (4), files (5), groundwater (11), statistics (6), view (1), history (1) y python (1). server_info se incluye siempre. Las herramientas se publican en un orden fijo, de modo que el cliente puede guardar la lista en caché.

ogr-slip2d-mcp --toolsets core,model,settings,analysis,view --workdir "C:\models"

5.1.6Trabajo sobre la ventana abierta del programa#

Desde la v0.1.207, el programa abre su puente para agentes al arrancar (Tools → Agent bridge (MCP), activado por defecto). Si OGR Slip2D está abierto, la llamada va a su ventana; si no, a los modelos propios del servidor. No importa en qué orden se abran el programa y el cliente, y una ventana que se cierra y se vuelve a abrir se encuentra de nuevo.

• Adónde va cada llamada. Una llamada que cita un project_id, job_id o result_id que ya tiene el servidor se queda en él, así que no se pierde un modelo empezado antes de abrir la ventana. Cualquier otra llamada va a la ventana si hay alguna que responda (la abierta más recientemente, si hay varias) y, en caso contrario, a los modelos propios del servidor. server_info indica adónde irá la siguiente llamada (attached_to_window: modo, si hay una ventana abierta, su id de proceso y su título, next_call_goes_to), y cada entrada de open_models indica in_window.
• Es el modelo del usuario. El usuario ve cada edición; cada edición del agente es un paso de Edit → Undo, y el agente puede deshacer los pasos del propio usuario; el lienzo se redibuja tras cada edición. Un análisis que ejecuta el agente aparece en el panel de resultados y en el lienzo, igual que si se ejecutara Compute. model_render(source="window") devuelve una captura del lienzo tal como está en pantalla.
• El trabajo sin guardar está protegido. project_new y project_open abren el modelo en la ventana, pero se niegan a hacerlo (E_CONFLICT) mientras esta tenga cambios sin guardar: el agente debe guardarlos con project_save o consultar al usuario. project_close nunca cierra el modelo de la ventana.
• Ocupada. Mientras la ventana está calculando (con su propio Compute o su barrido de desembalse, que usan el modelo abierto en otro hilo), una edición responde E_BUSY y hay que repetirla cuando la ventana haya terminado.
• Las rutas relativas se resuelven respecto a --workdir, el del servidor, que este envía a la ventana al conectarse (lo fija el último servidor que se conecta).
• Una ventana que se cierra a mitad de una llamada. Si la ventana se cierra mientras respondía a una llamada, esta no se repite, porque no se puede saber si llegó a ejecutarse: se responde E_CONFLICT y conviene revisar el modelo con project_summary antes de repetirla.

El puente escucha solo en 127.0.0.1, en un puerto que elige el sistema, y con un token aleatorio nuevo cada vez que arranca. La ventana anuncia ambos datos en ~/.ogr-slip2d/bridges/<pid>.json (puerto, token, id de proceso y título de la ventana); en sistemas POSIX, solo el usuario puede leer ese archivo. El archivo se borra cuando se desactiva el puente o se cierra la ventana, y el siguiente servidor que lo consulte elimina cualquier archivo cuyo puerto ya no responda. A una conexión cuya primera línea no lleva el token correcto se le responde E_UNAUTHORIZED y se cierra. Para mantener desactivado el puente, desmarca Tools → Agent bridge (MCP) o arranca el programa con python -m ogr_gui --no-agent-bridge (Sección 5.2).

5.1.7Herramientas#

Las 74 herramientas del perfil full, agrupadas como en la lista de herramientas del propio programa. C marca las 14 herramientas del perfil compact. Indicación es la anotación MCP que el servidor declara para cada herramienta (solo lectura, edición o destructiva) y que pueden usar los clientes que piden confirmación. Los parámetros exactos y sus descripciones los publica el propio servidor (tools/list).

Proyecto (core)#

Modelo (model)#

Detalles de boundary_add. Un contorno de material cerrado (closed=true) es un lentejón: una región propia y un hueco en la región que lo rodea (desde la v0.1.197). Un objeto de búsqueda por bloques indica su clase en block_object (desde la v0.1.232): window, line, point o polyline. Una polilínea proporciona a cada superficie de prueba dos puntos y el tramo de polilínea que hay entre ellos, y admite left_point y right_point (any, segment, end_point); dos puntos abiertos sin clase forman una línea, no una polilínea. Desde la v0.1.233, un objeto lleva además un group_id (un entero, 0 por defecto) que solo se tiene en cuenta si search.block_multiple_groups está activado: entonces cada grupo se busca por separado, el número de superficies se reparte entre los grupos y las polilíneas de grupos distintos pueden solaparse en x.

Cargas (loads)#

Una carga lineal normal al contorno o en ángulo con el contorno toma su dirección de la superficie del terreno en el punto donde se aplica (desde la v0.1.199): la normal apunta hacia el interior del terreno (en un vértice, según la bisectriz), y el ángulo se mide en sentido antihorario desde la superficie del terreno recorrida de izquierda a derecha, de modo que −90° corresponde a la normal. Una carga así se rechaza si no está sobre la superficie del terreno.

Soportes (supports)#

Búsqueda (search)#

Anotaciones (annotations)#

Archivos (files)#

Agua subterránea (groundwater, desde la v0.1.200)#

Unidades: alturas piezométricas en m y presión intersticial en kPa; permeabilidad, infiltración y caudal nodal en una misma unidad coherente (m/s). Desde la v0.1.200, cada modelo de permeabilidad toma la succión en la unidad de su propia definición: van Genuchten y Gardner, en altura de succión (α en 1/m); Brooks-Corey, Fredlund-Xing, Simple y la curva definida por el usuario, en succión matricial (kPa).

Estadística, retroanálisis y optimización (statistics, desde la v0.1.201)#

Los tres cálculos se ejecutan por la misma vía que analysis_run: sin norma de diseño dan el mismo resultado que antes; con ella, analizan el modelo con los coeficientes parciales aplicados.

Ajustes (settings)#

Análisis (analysis)#

Vista, historial y Python (view, history, python)#

5.1.8Recursos#

Muchos clientes nunca leen los recursos. Por eso, una versión corta de la guía acompaña a cada conexión como instrucciones del servidor; en ella figura cada regla que cambia un número, y se repite en las descripciones de las herramientas a las que afecta.

5.1.9Flujo de trabajo de modelado#

project_new → model_define → project_validate → analysis_configure
            → analysis_run → results_get / model_render → project_save

• Cada llamada devuelve o recibe un project_id; puede omitirse mientras solo haya un modelo abierto.
• analysis_run ejecuta cada método activado como una tarea en segundo plano y espera hasta wait_seconds (30 s por defecto, con --max-wait como tope). Si responde state: "running" con un job_id, consulta job_get (con espera) hasta que devuelva done; job_cancel mata todo el árbol de procesos de la tarea. El estado de una tarea es queued, running, done, failed, cancelled o crashed.
• Una tarea terminada lleva un result_id: con results_get(result_id, view=…) se obtienen summary, critical (con dovelas), top, minima o warnings, y model_render(result_id=…) dibuja sus superficies críticas. El servidor conserva los cinco últimos resultados de cada modelo.
• Los avisos son la forma en que el programa señala un problema que ha detectado, así que conviene leerlos antes de fiarse de un resultado.

Reglas que cambian el número#

Estas son las reglas que el servidor da a todos los agentes, porque cada una cambia un factor de seguridad sin provocar ningún error:

1. Una región a la que nadie asigna material toma el primero de la lista. Esta convención no avisa: project_summary indica, para cada región, si su material es assigned, inherited o default_first_material.
2. Un nivel freático o una línea piezométrica no tiene ningún efecto hasta que se asocia a materiales (model_define water_table.materials, o boundary_add assign_to).
3. En la búsqueda por rejilla, nx y ny son intervalos: puntos = nx + 1; un radius_increment de 10 da 11 radios por centro. Total de círculos = (nx + 1)(ny + 1)(radius_increment + 1).
4. analysis_run puede devolver state: "running" con un job_id: consulta job_get.
5. Un resultado marcado como stale se calculó sobre un modelo que ha cambiado desde entonces.
6. Un campo de agua subterránea por elementos finitos (groundwater_run) solo llega a los materiales cuya pore_pressure es fem.

La guía completa añade que, con una norma de diseño activada, el número que se obtiene es un factor de sobredimensionamiento, que debe superar 1, y no un factor de seguridad (los resultados indican en caption de cuál se trata); que failure_direction es left_to_right cuando el talud desciende hacia la derecha; y que el sistema de unidades de los ajustes solo cambia lo que muestra la interfaz.

5.1.10Errores#

Una herramienta que falla responde con un mensaje codificado, [E_CODE] message Hint: …; si el nombre es desconocido, se añaden los nombres conocidos más parecidos (Did you mean …?). Los códigos se enumeran en la Sección 5.5.4. Un ajuste que el análisis no leería se rechaza con el motivo en lugar de guardarse, y una tarea fallida o interrumpida se comunica como E_JOB_FAILED con su error.

5.1.11Modelo de seguridad#

python_exec: ejecución de código arbitrario#

El servidor publica siempre python_exec, que ejecuta código Python arbitrario en el proceso del servidor, con los permisos del usuario que lo arrancó; con el puente, lo ejecuta dentro del proceso de la ventana del programa. Es una decisión del propietario (2026-09-24), para cubrir lo que todavía no tiene herramienta. En consecuencia, quien pueda hablar con el servidor puede ejecutar código en la máquina, y todo lo que sigue se deriva de ello.

• El script dispone de project (el modelo abierto), api (todas las operaciones: api.material_set(...)), np, ogr_core, ogr_slip2d y result(result_id); se devuelve el valor de su última expresión.
• Todo el script es un paso de deshacer, que se revierte si lanza una excepción. La salida se trunca a 20 000 caracteres, y el valor devuelto, a 5 000.
• Un script no se puede detener: si no termina nunca, mantiene bloqueado su modelo hasta que acaba el proceso. Por eso los análisis son tareas y los scripts no.

Con stdio#

El servidor es un proceso hijo del cliente y no abre ningún puerto. El riesgo que queda es la inyección de instrucciones (prompt injection): un texto que lee el modelo (un archivo, una página web) puede pedirle que ejecute algo. La defensa son los clientes que piden confirmación antes de cada herramienta; conviene mantener esa confirmación activada para python_exec, que el servidor declara destructiva.

Con HTTP#

• Siempre un token, también en 127.0.0.1. Que sea «solo local» no es ninguna barrera: cualquier página web puede hacer que el navegador envíe peticiones a localhost. El token se compara en tiempo constante.
• Se comprueban Host y Origin (la protección del SDK contra DNS rebinding, activada): 421 para un Host ajeno y 403 para un Origin ajeno, incluso con el token.
• Fuera del bucle local, token explícito. En un host que no es de bucle local, el servidor exige un token explícito (--token, --token-file u OGR_MCP_TOKEN) y se niega a arrancar sin él (código de salida 2). --no-auth solo se acepta en bucle local.
• Un token en la línea de comandos es visible para otros usuarios de la máquina: es preferible usar --token-file u OGR_MCP_TOKEN.

El puente a la ventana#

El puente escucha solo en 127.0.0.1, con un token aleatorio nuevo en cada arranque, escrito en un archivo de la carpeta personal del usuario. Quien controla el puente maneja la ventana, python_exec incluido. No abre ningún acceso nuevo, porque leer ese archivo ya exige ser ese usuario en esa máquina; aun así, se puede desactivar en Tools → Agent bridge (MCP) o con --no-agent-bridge. Los tests del programa se ejecutan con su propia carpeta de descubrimiento vacía, de modo que un test que arranca un servidor no puede editar un modelo que el usuario tenga abierto.

En Internet (--public-url)#

• El servidor no abre ningún túnel por sí mismo; delante de él va un túnel o un proxy que termina HTTPS, o bien --tls-cert y --tls-key sirven HTTPS directamente.
• La aprobación se concede escribiendo el token del servidor en /approve, una página que indica qué cliente la solicita y adónde se le devolverá, y advierte de que aprobar le permite ejecutar todas las herramientas, python_exec incluido. Si el token es incorrecto, la respuesta se retrasa un segundo; tras 5 tokens incorrectos, la solicitud queda bloqueada; y tras 20 tokens incorrectos en 10 minutos, contando todas las solicitudes, se suspenden todas las aprobaciones durante un tiempo (como cualquiera puede abrir una solicitud nueva, un límite por solicitud no bastaría por sí solo para acotar los intentos de adivinar el token).
• Por la misma razón, con --public-url el token debe tener al menos 32 caracteres; uno generado tiene 43.
• Ningún otro sitio puede incrustar la página de aprobación en un marco (X-Frame-Options: DENY, frame-ancestors 'none'), y no se conservan ni la página ni su procedencia (no-store, no-referrer).
• Una aprobación produce un código de autorización (PKCE S256, de un solo uso, válido durante 5 minutos); una solicitud pendiente caduca a los 10 minutos. Los tokens emitidos son opacos y residen en memoria, así que reiniciar el servidor los revoca todos: los tokens de acceso duran una hora; los de actualización, treinta días, y se rotan en cada uso. La revocación está habilitada; las concesiones por aserción de identidad se rechazan.
• El token del propio servidor sigue valiendo como Authorization: Bearer para los clientes que envían cabeceras.
• Los clientes se registran dinámicamente (RFC 7591), y solo con URI de redirección incluidas en una lista de permitidas: las direcciones de retorno de los clientes alojados que figuran en ogr_mcp/oauth.py, las direcciones de bucle local y las añadidas con --oauth-redirect.
• No se ofrecen documentos de metadatos de ID de cliente (Client ID Metadata Documents): obligarían al servidor a descargar un documento de otro sitio, y el servidor no hace llamadas de red.
• --no-auth nunca se combina con --public-url, y una URL pública http:// solo se acepta en bucle local, para pruebas. El Host y el Origin públicos se suman a los permitidos; cualquier otro sigue recibiendo 421 o 403.

Archivos, red y telemetría#

• Las rutas relativas se resuelven respecto a --workdir. Al guardar, nunca se sobrescribe un archivo existente sin overwrite=true, salvo el propio archivo del modelo, pues eso es lo que significa guardar.
• El servidor no hace ninguna llamada de red por su cuenta. La dependencia opentelemetry-api que trae el SDK es solo la API: sin un SDK de telemetría configurado, no exporta nada.