MCP server

ogr-slip2d-mcp is the official Model Context Protocol (MCP) server of OGR Slip2D. With it, an AI agent can build a slope model, run the analysis and read and draw the results, either on models of the server's own or on the model open in the program window, where the user sees each edit and can undo it. This page is the technical reference (options, transports, the 74 tools, resources and the security model); how to connect a particular client is explained on the AI page.

5.1.1What it is#

• A thin layer over the operations layer. Each tool is one operation of ogr_api (73 operations), plus server_info, which only the server has. The tools are written by hand, because a tool's description and parameter types are the whole interface a language model sees; a test keeps the two in step: every operation has a tool, every tool calls an operation and every tool parameter is a parameter of its operation. The same operations can be called from Python (Section 5.3).
• The official SDK. The server is built on the MCP SDK for Python (mcp ≥ 2.1 and < 3, MIT licence), installed by the [mcp] extra. The desktop program does not need it.
• Two transports. Standard input/output (the default) and streamable HTTP, with a bearer token and, for clients that reach it over the Internet, OAuth 2.1.
• SI units everywhere (m, kN, kPa, kN/m³, degrees), x to the right and y up, whatever unit system the window displays.
• Analyses are jobs. An analysis runs in a child process that can be cancelled; every edit of a model is one undo step.
• The open window first. If OGR Slip2D is open, calls work on its window (Section 5.1.6).

5.1.2Installation#

From a clone of the repository, with Python 3.11 or later:

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

Without the SDK the server stops with exit code 3 and asks for the extra (pip install "ogr-slip2d[mcp]"). ogr-slip2d-mcp --help lists every option. Client configuration files, for desktop chat applications, local models and HTTP clients, are on the AI page.

5.1.3Command-line options#

Nothing is written on standard output, because over stdio that stream carries the protocol. Messages go to standard error, or to --log-file.

5.1.4Transports#

Standard input/output#

The client starts the server as a child process and talks to it through its standard streams; no port is opened. This is the transport of desktop chat applications, coding agents and local-model clients.

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

Streamable HTTP#

With --transport http the server answers at http://HOST:PORT/mcp, stateless and with JSON responses. Every request needs Authorization: Bearer <token>; a missing or wrong token is answered 401. The token comes from --token, --token-file or OGR_MCP_TOKEN, in that order. When none is given on a loopback host, the server generates one (43 characters) and prints it on standard error when it starts.

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

The Host and Origin headers are checked even when the token is right: a Host that is not this server's is answered 421 and a foreign Origin 403. Allowed hosts are 127.0.0.1, localhost, [::1] and --host, at the port; allowed origins are 127.0.0.1 and localhost at the port, plus each --allow-origin. With --tls-cert and --tls-key the same endpoint is served over HTTPS.

OAuth 2.1 for clients on the Internet#

Some hosted clients connect only to a public HTTPS server and only through OAuth. For them, the server keeps listening on 127.0.0.1, a tunnel or reverse proxy that terminates HTTPS is placed in front of it, and the server is told its public address with --public-url. It then acts as its own OAuth 2.1 authorization server: PKCE with S256, dynamic client registration and tokens bound to the resource <public-url>/mcp. Access is granted by typing the server's token on its page <public-url>/approve; whoever knows the token is taken to be the owner. The static token keeps working as a bearer header for clients that can send one. The limits are listed under Section 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.5Profiles and toolsets#

A small local model loses its way among many tools, and every tool's description costs context on every request. The server therefore offers two profiles:

• full (default): all 74 tools.
• compact: the 14 tools a complete build–run–read cycle needs: 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 and python_exec. model_define builds the whole geometry in one call and python_exec covers the rest. They are marked C in the tables of Section 5.1.7.

--toolsets replaces the profile by a list of toolsets: core (10 tools), model (9), settings (3), analysis (7), loads (5), supports (6), search (5), annotations (4), files (5), groundwater (11), statistics (6), view (1), history (1) and python (1). server_info is always included. Tools are published in a fixed order, so a client can cache the list.

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

5.1.6Working on the open program window#

Since v0.1.207 the program opens its agent bridge when it starts (Tools → Agent bridge (MCP), ticked by default). If OGR Slip2D is open, a call goes to its window; if it is not, to models of the server's own. The order in which the program and the client are opened does not matter, and a window that is closed and opened again is found again.

• Which call goes where. A call that names a project_id, job_id or result_id the server holds stays with the server, so a model begun before the window was opened is not lost. Any other call goes to the window if one answers (the most recently started one when several are open) and otherwise to the server's own models. server_info says where the next call goes (attached_to_window: mode, whether a window is open, its process id and title, next_call_goes_to), and each entry of open_models says in_window.
• It is the user's model. The user sees every edit; each edit of the agent is one step of Edit → Undo, and the user's own steps can be undone by the agent; the canvas is redrawn after each edit. An analysis the agent runs appears in the results panel and on the canvas, as a Compute would. model_render(source="window") returns a capture of the canvas as it is on screen.
• Unsaved work is protected. project_new and project_open open in the window and refuse (E_CONFLICT) while it has unsaved changes: the agent has to save them with project_save or ask the user. project_close never closes the window's model.
• Busy. While the window is computing (its own Compute or drawdown sweep, which use the live model on another thread), an edit answers E_BUSY, to be retried when the window has finished.
• Relative paths are resolved against the server's --workdir, which the server sends to the window when it connects (the last server to connect sets it).
• A window that closes mid-call. A call the window was answering when it closed is not repeated, because whether it ran cannot be known: it answers E_CONFLICT, and the model should be checked with project_summary before repeating it.

The bridge listens only on 127.0.0.1, at a port chosen by the system, with a new random token each time it starts. The window announces both in ~/.ogr-slip2d/bridges/<pid>.json (port, token, process id and window title); on POSIX systems only the user can read that file. It is deleted when the bridge is switched off or the window closes, and a file whose port no longer answers is removed by the next server that looks. A connection whose first line does not carry the right token is answered E_UNAUTHORIZED and closed. To keep the bridge off, untick Tools → Agent bridge (MCP) or start the program with python -m ogr_gui --no-agent-bridge (Section 5.2).

5.1.7Tools#

The 74 tools of the full profile, grouped as in the program's own tool list. C marks the 14 tools of the compact profile. Hint is the MCP annotation the server declares for the tool (read-only, edit or destructive), which clients that ask for confirmation can use. The exact parameters and their descriptions are published by the server itself (tools/list).

Project (core)#

Model (model)#

boundary_add details. A closed material boundary (closed=true) is a lens: a region of its own and a hole in the region around it (since v0.1.197). A Block Search object carries its kind in block_object (since v0.1.232): window, line, point or polyline. A polyline gives each trial surface two points and the stretch of polyline between them, and accepts left_point and right_point (any, segment, end_point); two open points without a kind are a line, not a polyline. Since v0.1.233 an object also carries a group_id (an integer, 0 by default) that is read only with search.block_multiple_groups on: each group is then searched separately, the number of surfaces is shared among the groups, and polylines of different groups may overlap in x.

Loads (loads)#

A line load normal to the boundary or at an angle to the boundary takes its direction from the ground surface at its point (since v0.1.199): the normal points into the ground (at a vertex, along the bisector), and the angle is measured anticlockwise from the ground surface traversed from left to right, so −90° is the normal. Off the ground surface such a load is refused.

Supports (supports)#

Search (search)#

Annotations (annotations)#

Files (files)#

Groundwater (groundwater, since v0.1.200)#

Units: hydraulic heads in m and pore pressure in kPa; permeability, infiltration and nodal flow in one consistent unit (m/s). Since v0.1.200 each permeability model takes suction in the unit of its own definition: van Genuchten and Gardner in suction head (α in 1/m); Brooks–Corey, Fredlund–Xing, Simple and the user-defined curve in matric suction (kPa).

Statistics, back analysis and optimisation (statistics, since v0.1.201)#

The three runs go through the same door as analysis_run: without a design standard they give the same results as before; with one, they analyse the factored model.

Settings (settings)#

Analysis (analysis)#

View, history and Python (view, history, python)#

5.1.8Resources#

Many clients never read resources. A short version of the guide therefore travels with every connection as the server's instructions, and every rule that changes a number is in it and repeated in the tool descriptions where it applies.

5.1.9Modelling workflow#

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

• Each call returns or takes a project_id; it may be omitted while only one model is open.
• analysis_run runs every enabled method as a background job and waits up to wait_seconds (30 s by default, capped at --max-wait). If it answers state: "running" with a job_id, poll job_get (with a wait) until done; job_cancel kills the job's whole process tree. A job is queued, running, done, failed, cancelled or crashed.
• A finished job carries a result_id: results_get(result_id, view=…) with summary, critical (with slices), top, minima or warnings, and model_render(result_id=…) draws its critical surfaces. The server keeps the last five results of each model.
• Warnings are how the program reports a problem it has noticed, so they should be read before a result is relied on.

Rules that change the number#

The rules the server gives every agent, because each of them changes a factor of safety without an error:

1. A region nobody assigned takes the first material of the list. The convention is silent: project_summary says for each region whether its material was assigned, inherited or the default_first_material.
2. A water table or piezometric line does nothing until materials point at it (model_define water_table.materials, or boundary_add assign_to).
3. The grid search nx and ny are intervals: points = nx + 1; radius_increment 10 means 11 radii per centre. Total circles = (nx + 1)(ny + 1)(radius_increment + 1).
4. analysis_run may return state: "running" with a job_id: poll job_get.
5. A result marked stale was computed on a model that has changed since.
6. A finite-element groundwater field (groundwater_run) reaches only the materials whose pore_pressure is fem.

The full guide adds that, with a design standard on, the number reported is an over-design factor, which must exceed 1, not a factor of safety (results say which in caption); that failure_direction is left_to_right when the slope goes down to the right; and that the unit system in the settings only changes what the interface displays.

5.1.10Errors#

A tool that fails answers with a coded message, [E_CODE] message Hint: …; an unknown name comes with the closest known names (Did you mean …?). The codes are listed in Section 5.5.4. A setting that the analysis would not read is refused with the reason instead of being stored, and a failed or crashed job is reported as E_JOB_FAILED with its error.

5.1.11Security model#

python_exec: arbitrary code execution#

The server always publishes python_exec, which runs arbitrary Python in the server process with the permissions of the user who started it; through the bridge, it runs inside the program window's process. It is the owner's decision (2026-09-24), to cover whatever has no tool yet. As a result, whoever can talk to the server can run code on the machine, and everything below follows from that.

• The script sees project (the live model), api (every operation: api.material_set(...)), np, ogr_core, ogr_slip2d and result(result_id); the value of its last expression is returned.
• The whole script is one undo step, rolled back if it raises. Output is cut at 20 000 characters, and the returned value at 5 000.
• A script cannot be stopped: one that never ends holds its model's lock until the process exits. That is why analyses are jobs and scripts are not.

Over stdio#

The server is a child process of the client and opens no port. The remaining risk is prompt injection: a text the model reads (a file, a web page) can ask it to run something. Clients that ask for confirmation before each tool are the defence; it should stay on for python_exec, which the server declares destructive.

Over HTTP#

• A token always, also on 127.0.0.1. "Only local" is not a boundary: any web page can make the browser send requests to localhost. The token is compared in constant time.
• Host and Origin are checked (the SDK's DNS-rebinding protection, switched on): 421 for a foreign Host, 403 for a foreign Origin, even with the token.
• An explicit token off loopback. On a host that is not loopback the server requires an explicit token (--token, --token-file or OGR_MCP_TOKEN) and refuses to start without one (exit code 2). --no-auth is accepted only on loopback.
• A token on the command line is visible to other users of the machine: --token-file or OGR_MCP_TOKEN are preferable.

The bridge to the window#

The bridge listens only on 127.0.0.1, with a new random token at each start, written to a file in the user's home folder. Whoever has the bridge drives the window, python_exec included. It opens no new access, because reading that file already requires being that user on that machine; it can still be switched off in Tools → Agent bridge (MCP) or with --no-agent-bridge. The program's tests run with an empty discovery folder of their own, so a test that starts a server cannot edit a model the user has open.

On the Internet (--public-url)#

• The server opens no tunnel by itself; a tunnel or proxy that terminates HTTPS goes in front of it, or --tls-cert and --tls-key serve HTTPS directly.
• Approval is granted by typing the server's token on /approve, a page that names the client asking and where it will be sent back, and warns that approving lets it run every tool, python_exec included. A wrong token is answered after a delay of one second; after 5 wrong tokens a request is locked; after 20 wrong tokens within 10 minutes, counting every request, all approvals stop for a while (anyone can open a new request, so a per-request limit alone would not bound the guessing).
• For the same reason the token must have at least 32 characters with --public-url; a generated one has 43.
• No other site can frame the approval page (X-Frame-Options: DENY, frame-ancestors 'none'), and neither the page nor where it came from is kept (no-store, no-referrer).
• An approval yields an authorization code (PKCE S256, single use, valid for 5 minutes); a pending request expires after 10 minutes. Tokens issued are opaque and live in memory, so restarting the server revokes them all: access tokens last one hour, refresh tokens thirty days and are rotated at each use. Revocation is enabled; identity-assertion grants are refused.
• The server's own token keeps working as Authorization: Bearer for clients that send headers.
• Clients register dynamically (RFC 7591), and only with redirect URIs on an allowlist: the callback addresses of the hosted clients listed in ogr_mcp/oauth.py, loopback addresses, and those added with --oauth-redirect.
• Client ID metadata documents are not offered: they would make the server fetch a document from another site, and the server makes no network calls.
• --no-auth never goes with --public-url, and an http:// public URL is accepted only on loopback, for testing. The public Host and Origin join the allowed ones; any other still gets 421 or 403.

Files, network and telemetry#

• Relative paths are resolved against --workdir. Saving never overwrites an existing file without overwrite=true, except the model's own file, which is what saving means.
• The server makes no network call of its own. The opentelemetry-api dependency that the SDK brings is only the API: without a telemetry SDK configured, it exports nothing.