Optional MCP Server¶

MCP settings/set accepts analysis_method: "linear" | "p_delta". Read the schema before editing. run_analysis uses this saved choice and returns unsupported_analysis for P-Delta models containing unsupported entities. analysis_status.snapshot and read_results include analysis_method and method_label, alongside the snapshot identity. Poll normally until the job stops.

Install the optional extra and launch with it from the repository:

uv sync --extra mcp
uv run --extra mcp brecon

A normal installation needs no MCP/server packages. Tools > Automation Server opens a native panel for this project window. The server starts off; choose a port (default 8765), then Start. It binds only 127.0.0.1 and uses the official MCP Python SDK's Streamable HTTP transport at http://127.0.0.1:8765/mcp. Missing dependencies and occupied ports appear in the panel without installing anything automatically. Use a separate port for each project window.

Use Copy configuration for clients accepting the common mcpServers format, or copy the endpoint into a client's Streamable HTTP settings. Require token starts checked. With it checked, clients need an Authorization: Bearer <token> header; copy the token after Start. For example (replace the placeholder with the copied token; use the actual port):

{
  "mcpServers": {
    "Brecon": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {"Authorization": "Bearer <copied-token>"}
    }
  }
}

For a connection that needs no token updates, stop the server, uncheck Require token, then Start again. This preference is remembered in the app settings across GUI restarts. The checkbox can only change while the listener is stopped. In this mode no token is generated, Copy token is disabled and Copy configuration includes only the URL. An LM Studio entry can then remain:

"pynite": {
  "url": "http://127.0.0.1:8765/mcp"
}

Recheck Require token while stopped to restore authentication. When required, every start generates a new token; tokens are never persisted. The panel masks the token and logs only fixed request names/status codes, omitting arguments, model values, paths and credentials. Status shows the last accepted request and its count, rather than claiming a persistent client connection. Closing the panel leaves the server running; Stop or closing the project window stops access. Stop invalidates queued commands immediately. A solve already started continues under the normal GUI controls; cancel it separately.

MCP mode gives the server exclusive control of this project while it runs. Use the button in the status bar or Automation Server panel; it stays disabled until the server is running. Entering switches to Select, cancels drawing and discards unapplied inspector inputs without changing committed model data. Finish any open modal editing dialog before entering. Menus, toolbars, canvas, model/results panels and manual shortcuts are locked, while model updates and solver progress still appear. MCP commands can edit/analyze without the normal editor-busy check in this mode; tool permissions and session/revision guards still apply. read_model reports mcp_mode so clients can see who controls the editor.

Click Leave MCP mode in the status bar or panel to return to manual control. The Automation Server panel remains available for permissions, cancellation via the client, and Stop. Stopping the server or losing its listener automatically unlocks the editor. Closing the panel leaves MCP mode active, with the status-bar release button available. Closing the project window releases the lock before the normal cancellation and unsaved-change prompt. This mode is per-window, starts off and is not saved in project files. Ordinary manual controls return with their current result/analysis availability intact.

Both a permission group and its individual tool switch must be enabled. Model and result reads start enabled; edits and analysis start disabled. Switches take effect during discovery, on every call and again before GUI-thread dispatch. The server always rejects non-loopback peers and invalid Host/Origin headers. When Require token is checked, it also rejects missing, incorrect or duplicate authorization headers. Token-free mode retains tool permissions, MCP mode and revision/session checks. Requests are limited to 1 MiB, batches to 512 KiB/500 operations, and the GUI queue to 64 commands. Queued commands time out after 30 seconds; read the current model before retrying a mutation whose response was lost.

The MCP reference resource brecon://automation/reference also documents both dimensions. Tool descriptions name the exact support/member/load fields and direct clients to the schema before editing. Since clients may not pass resources into a model's context automatically, read_model includes the schema directly and read_schema exposes it as a normal model-callable tool.

The GUI owns one project session per open window; it is not a chat/client session. There are no create/list-session tools. Call read_model without a session ID, inspect its schema, and use read_schema for examples. Later model reads may use include_schema: false to reduce response size. Use the returned session_id for subsequent calls and its revision as expected_revision for edits/analysis. Opening another project changes the session; unknown or old IDs return stale_session. Discover the new ID with read_model instead of inventing one. Intervening GUI edits, undo/redo and display-unit changes invalidate the expected revision. Engineering edits clear the active result; display-unit changes preserve its snapshot identity and convert its report values. Failed or cancelled reruns can retain previous results, so inspect analysis_state before treating a snapshot as current. Supply snapshot_id to reject a replaced snapshot. Responses use {"ok": true, "data": ...} or {"ok": false, "error": {"code": ..., "message": ...}}; MCP tool errors also set isError. Remote analysis failures populate Model Findings and job status without opening a warning popup.

Analysis starts asynchronously. Retain the returned job_id and poll analysis_status(session_id, job_id) until running is false. Inspect state and error; read results after a successful Current state. phase is human-readable progress text, not a fixed enumeration. A replaced job returns unknown_job. Select a result combination from available_combinations in status; omit the combination to use the snapshot default. Model-defined combination names/factors are also available in read_model.model.combinations. Only one active result snapshot is retained; there is no historical snapshot store or enumeration.

Batch inputs use canonical inch-kip units, degrees for angles and member fractions for load positions. Ordinary supports are fields on nodes. Spatial surface_supports is a separate geometry-owned outer-edge map; put replaces the whole map for that surface, and surface deletion requires removing its dependent support/pressure maps in the same batch. put merges existing entity fields or creates an entity using its normal defaults; delete requires explicit dependent-reference updates in the same batch. Numeric material/section edits clear preset/catalog provenance unless explicitly supplied. Project validation runs once after all operations, so a rejected batch creates no partial changes or undo step. Operation-local failures include error.operation_index, a zero-based position in the submitted operations list (including SDK argument validation when an item has the wrong type). Whole-batch size/reference/constraint failures omit the index because several cooperating operations may cause or resolve them. Every failure leaves the model and undo history unchanged; correct the batch and resubmit it.

For example, after obtaining the current session and revision:

{
  "session_id": "<read_model.session_id>",
  "expected_revision": 7,
  "operations": [
    {"op": "put", "collection": "nodes", "key": "N2", "value": {"x": 480}},
    {"op": "put", "collection": "load_cases", "key": "Wind"},
    {"op": "put", "collection": "combinations", "key": "Service", "value": {"Wind": 1}}
  ]
}

Entity collections are nodes, members, loads, materials, sections and combinations; cases use load_cases with no value. For settings, use op: "set" and a value containing only unit_system, grid, default_material, default_section, default_load_case, self_weight_case or self_weight_factor. Spatial projects also support surfaces and surface_pressures collections and settings.surface_analysis_enabled. Surface put merges recipe fields and nested recipe-local material fields; generator parameters, control lists and openings replace whole values. Copying a full read_model recipe is supported; its fixed format/version/unit metadata must remain valid. The schema describes all seven generators, exact defaults, fields, pressure normals and mesh budgets.

Pressure-map put uses a surface ID as key and replaces its complete {case: pressure} map, in canonical kip/in2 regardless of display units. Deleting a surface or load case requires explicit pressure-map cleanup and other reference updates in the same batch. No dependent assignment is silently dropped. For example, in an existing matching 3D frame (with a Gravity case):

[
  {"op":"put","collection":"surfaces","key":"Floor1","value":{
    "plane":"XZ","origin":[0,144,0],"parameters":{"width":240,"height":180},
    "mesh_size":60,"thickness":6}},
  {"op":"put","collection":"surface_pressures","key":"Floor1","value":{"Gravity":0.001}},
  {"op":"set","collection":"settings","value":{"surface_analysis_enabled":true}}
]

This is the operations array for apply_batch; include the current session and expected revision. Positive XZ pressure acts in -Y. Coupled batches require only rectangular Quad surfaces and a conforming connected interface. Edit frame nodes, mesh placement/controls, cases and assignments together when they depend on each other. Alternatively stage geometry with coupling disabled, then enable it in a complete valid batch. Existing geometry-only analysis guards remain in force. Surface editing uses the same Model edits group/tool switch, revision/session checks, GUI dispatch and one-step undo as other batch edits. Native MCP mode also applies. Multistorey regressions check two slabs at separate levels, symmetric base load transfer, combinations, refinement and frame/slab self-weight.

Model reads expose the entity fields for each project's 2D/3D dimension. Active input drafts, gestures and editing dialogs block remote edits/analysis. Drawing mode also blocks them: switch to Select mode first. editor_busy identifies the blocker and how to finish/cancel it. The automation panel, read-only fields and inputs in another project window do not count as unfinished model input. Accepted edits follow the existing live-recalculation preference, including automatic solves when live mode is enabled. Analysis progress/cancellation uses the existing isolated worker and preserves previous results on failure/cancellation.

There are no arbitrary Python/shell execution, project file-management or separate REST tools. The user opens and saves files normally. Optional viewport capture remains a follow-up. The server controller and command bridge use only base desktop imports; optional SDK/HTTP imports occur on Start. The HTTP thread queues commands onto Qt's main thread, where permissions, session and revision are checked before using the existing undo/analysis/report workflows.

Automation tests cover base imports without optional packages, missing-extra messages, lifecycle/port conflicts, token rotation, HTTP authentication/Host/Origin validation, request limits, permission revocation, queued cancellation, GUI-thread dispatch, atomic edits/undo, stale revisions/sessions, result pagination and live wire analysis success/cancellation. Install the extra to include SDK wire tests:

uv run --extra mcp python -B -m unittest discover -s tests -p 'test_qt_automation*.py'

Source: GUIDE.md. This manual follows the current repository; the published rc1 wheel has a smaller feature set.