Agent interface (MCP)

Connect#

The service mounts an MCP endpoint (streamable HTTP, stateless) at /mcp:

bash

claude mcp add --transport http gyre http://HOST:8600/mcp

For clients that speak stdio only, a proxy forwards to a deployment:

bash

claude mcp add gyre -- python -m gyre.agent --service http://HOST:8600

If the deployment sets GYRE_API_TOKEN, pass it as a bearer token (HTTP) or --token (proxy).

python -m gyre.agent is a second entry point, separate from the gyre program (it is not in the command-line reference).

Option	Default	Meaning
`--service URL`	the environment variable `GYRE_SERVICE_URL`, else `http://127.0.0.1:8600`	the deployment the proxy forwards to
`--token TOKEN`	the environment variable `GYRE_API_TOKEN`, else none	bearer token sent with every request to the deployment
`--transport stdio\\|streamable-http`	`stdio`	how the proxy itself talks to its MCP client. `stdio` is what a client that starts the proxy as a subprocess expects; `streamable-http` makes the proxy an HTTP MCP server of its own, on the MCP SDK’s default address

The proxy holds no state and no solver: every tool call becomes a request to the deployment’s REST API, with a timeout of 900 seconds per request.

Tools#

tool	purpose
`gyre_info`	Identify this Gyre deployment: version, source commit, device, endpoints, uptime.
`list_presets`	List built-in cases (name, description, size estimate) under `presets`. Start here.
`get_case_schema`	JSON Schema of a case specification (mesh, flow, discretization, solver).
`validate_case`	Dry-run a case without solving: resolved spec, element/DOF estimate, chosen device.
`submit_job`	Queue a steady flow analysis and return the job record.
`get_job`	Job state (queued/running/succeeded/failed/cancelled), progress and result summary.
`get_job_result`	Result of a finished job.
`get_job_events`	Progress events of a job (nonlinear iterations etc.) starting at sequence `since`.
`list_jobs`	Recent jobs under `jobs`, newest first; optionally filter by state.
`cancel_job`	Cancel a queued or running job.
`get_job_artifact`	Read a file a job produced.
`open_session`	Open a warm analysis session (a dedicated solver process) for repeated evaluations.
`session_evaluate`	Set inputs (e.g. {“alpha_deg”: 3.0, “mach”: 0.55}), converge the flow, return outputs.
`session_gradients`	Exact total derivatives d(of)/d(wrt) at the session’s current converged state.
`session_error_estimate`	Adjoint-weighted-residual discretization-error estimate for outputs `of`.
`session_adjoint`	Reverse (adjoint) total product at the session’s converged state: the coupled-adjoint building block.
`session_surface`	Surface nodes of the session’s case: `coordinates` (one row per node, the nodes that the input `x_surface` displaces and on which `f_surface` acts), the current `displacement` and `nodes`. Arrays are summarised unless `full_arrays`.
`session_state`	Current inputs of a session, whether a flow state exists (`solved`), whether the last evaluation converged (`converged`) and the residual norm of the kept state.
`get_session`	A session’s case, device, counters and `interface` (inputs with shapes and current values, outputs); `commands` lists what `session_command` accepts when the solver process reports it.
`session_command`	Run any command of the session’s solver process (generic pass-through).
`list_sessions`	Open sessions (under `sessions`) with their case, device, call counts and idle time.
`close_session`	Close a session and free its solver process.
`list_meshes`	Meshes in this deployment’s mesh store, under `meshes`: name, size, element count, geometry order, boundary groups (faces per group), bounding box, sha256.
`upload_mesh`	Store a mesh file so that cases can use it; returns its summary.
`inspect_mesh`	Summary of a stored mesh: bytes, sha256, dim, elements, geometry_order, nodes, boundaries (faces per group), bounding_box and quality numbers.
`delete_mesh`	Remove a mesh from the store (jobs still queued on it will fail).
`list_pipelines`	Declarative pipelines of this deployment, under `pipelines`.
`run_pipeline`	Start a pipeline run (a DAG of cached stages: solves, sweeps, gates, reports).
`get_pipeline_run`	Status and progress of a pipeline run.
`list_pipeline_runs`	Recent pipeline runs under `runs`, newest first (id, pipeline, status, times).
`cancel_pipeline_run`	Cancel an active pipeline run (the engine and the stage it is running are terminated); returns the run’s status, `cancelled` once its processes have ended. Stages that had completed stay in the stage cache. A finished run is returned as is.
`get_pipeline_artifact`	Files a stage of a pipeline run produced.
`search_docs`	Full-text search of the Gyre documentation served with this deployment.
`read_doc`	Read a documentation page as Markdown (math in LaTeX). `path` comes from `search_docs` (or use “llms.txt” for the site index). Long pages are paged with `offset`.

Explore. list_presets → validate_case (size, device, warnings) → get_case_schema when a field name is needed.

One-shot analysis. submit_job with wait_seconds (short jobs finish within the call) → otherwise get_job with wait_seconds until state is succeeded → get_job_result.

Design loop or sweep. open_session once → repeat session_evaluate and session_gradients → close_session. Sessions keep compiled kernels and warm-start each solve.

Your own geometry. upload_mesh (a Gmsh .msh file of quadrilaterals or hexahedra with a named physical group on every boundary, or a Gyre .npz file) → read boundaries in the returned summary → validate_case with mesh: {generator: "file", params: {path: <name>}} and one condition per group in discretization.boundaries → submit_job or open_session. list_meshes, inspect_mesh and delete_mesh manage the store. See Mesh files.

Accuracy on demand. submit_job with adapt_output and adapt_tolerance (and optionally adapt_max_order, default 5) raises the polynomial degree from the case’s discretization.order until the estimated error of that output meets the tolerance. get_job_result returns the adaptation section by default; read met before relying on the value.

Trust but verify. session_error_estimate for the discretization error of an output; search_docs / read_doc for methods, limits and verification evidence.

One code path. Every tool calls the REST API; an agent gets exactly the behaviour a program gets.
Structured, stable results. JSON with fixed keys. Arrays longer than a couple of dozen entries are replaced by {"_array": true, "shape", "min", "max", "l2_norm", "head"} unless full_arrays is set — shape sensitivities and histories would otherwise flood the context.
Errors that teach. A failure relayed from the REST API returns {"ok": false, "status", "error": {"type", "message", "hint"}}; the hint names the valid alternatives or the next call to make. The documentation tools report their own failures in the same form without status (read_doc omits the hint for an invalid path).
Refusals before a request. A mesh name that is not a bare file name ending in .msh or .npz returns {"ok": false, "status": 422, "error": {"type": "InvalidMeshName", …}} without a request to the service. upload_mesh takes content as text (encoding="text", the default) or base64 (encoding="base64", needed for .npz); invalid base64 or another encoding returns InvalidEncoding. adapt_output and adapt_tolerance must be given together; one without the other returns a ValidationError.
Bounded waits. Long work is asynchronous; waits are capped at 300 seconds per call, so an agent stays responsive and can report progress with get_job_events.
Self-description. The server’s instructions summarise conventions (non-dimensional units, radians, input and output names); validate_case and the session interface report sizes, shapes and current values.

text

→ open_session(case="naca0012_euler")
← {"id": "ses-…", "interface": {"inputs": {"mach": …, "alpha": …, "x_surface": {"shape": [128, 2]}},
                                 "outputs": {"cl": …, "cd": …, "f_surface": {"shape": [128, 2]}}}}
→ session_evaluate(session_id, inputs={"alpha_deg": 2.0})
← {"converged": true, "reason": "residual tolerance reached", "nonlinear_iterations": 16,
   "outputs": {"cl": 0.278767, "cd": 0.000949, …}, …}
→ session_gradients(session_id, of=["cl"], wrt=["alpha_deg", "x_surface"])
← {"derivatives": {"cl": {"alpha_deg": 0.135059,
                          "x_surface": {"_array": true, "shape": [128, 2], "l2_norm": 61.73, …}}},
   "info": {"mode": "adjoint", "linear_solves": [{"output": "cl", "iterations": 51, …}], …}}
→ session_evaluate(session_id, inputs={"alpha_deg": 2.5})        # warm start
← {"converged": true, "nonlinear_iterations": 6, "outputs": {"cl": 0.345916, "cd": 0.001074, …}, …}
→ close_session(session_id)
← {"id": "ses-…", "closed": true}

Recorded from a service running revision 5ee1cdc on the CPU; numbers are shortened and … marks omitted keys. alpha_deg derivatives are per degree: 0.135059 per degree is the 7.7383 per radian that a job with wrt: ["alpha"] returns for the same case. The warm-started second evaluation needed 6 nonlinear iterations instead of 16. The recording is not kept in the repository: the coefficients and gradients were reproduced by an independent command-line run of the same case, the iteration counts were not (what stands behind the replies). The agent example shows a complete exchange.

Resources: gyre://presets and gyre://schema/case. Prompts: analyze_case (run, check convergence, report outputs with error estimates and provenance) and gradient_check (verify an adjoint gradient against finite differences in a session).

The site publishes llms.txt (an index of pages with summaries), the Markdown source of every page next to its HTML, and a search index. search_docs ranks pages by term matches in title, headings, summary and body; read_doc returns Markdown with LaTeX math, paged by character offset. An agent can therefore ground a statement about, say, adjoint consistency in the page that defines it and in the verification study that tests it.