Connect an AI assistant with MCP

Connect to BGModeller

Model Context Protocol (MCP) lets an assistant call BGModeller tools. You need a client that supports remote Streamable HTTP MCP servers and an internet connection. The guide can be read offline; the tools run on the public server.

For large dynamic simulations, the client must also be able to receive, save and process results programmatically in files. MCP support alone is insufficient. The assistant must check these capabilities before submission; if they are unavailable, warn the user before calling simulate_model. See working with large results.

In your client's MCP settings, add a remote server with these values. Enable its tools, reconnect if needed, and ask the assistant to call get_capabilities. The URL is a protocol endpoint: opening it as a normal browser page does not test the connection.

Codex CLI example

codex mcp add bgmodeller --url https://bgmodeller.mkefweb.com/mcp
codex mcp list

Reconnect or start a new session if the tools do not appear. See the official OpenAI documentation for the Codex MCP connection pattern. Other clients use their own settings interface; select Streamable HTTP and the same server URL.

Available tools

Tool names below are the server names; your client may display a prefix. All physical quantities use SI units.

Read the guide and individual blocks

Your assistant can read the guide directly through MCP without a separate browser tool. Reuse known topic and section IDs for targeted get_documentation calls. When IDs are unknown, list_documentation returns topics with titles, topic IDs and sections. Block sections include a component type; primitive sections also identify their physical domain. Reuse retrieved documentation within the task.

Example tool calls to read the cylinder reference:

list_documentation({"language":"en"})
get_documentation({"topic":"cylinder","language":"en"})
get_documentation({"topic":"cylinder","section":"block-CylinderDA","language":"en"})

The first call is needed only to discover unknown IDs; the second reads the whole topic and the third reads just the block section. Use "language":"ru" for Russian; English is the default when omitted. For a hydraulic resistance, select "topic":"hydraulics","section":"block-R"; for a mechanical damper, use "topic":"mechanics","section":"block-R". Use known or discovered IDs rather than supplying a URL or file path.

In the response, data.content holds the text, data.url links to its source page or section, and data.links lists related topics. To follow a link, pass its topic, language and optional section to another get_documentation call. Do not pass the entire link object: title and url are not tool arguments.

The text comes from the same guide shown in the browser. Equations, tables, captions and diagram descriptions are included; images are not returned. Open data.url to inspect a drawing. Subscripts and superscripts appear as A_{A} and x^{2} in the text.

Documentation reads run no calculation and need no job token, but use the shared API request-rate allowance. If the new tools do not appear after a server update, reconnect MCP in your client. For a topic or section error (404), refresh the IDs with list_documentation.

Example: simulate a mechanical model

Try this prompt after connecting:

1. Read get_capabilities and get_library once, then get_example with {"name":"mechanical_two_mass"} and the relevant mechanical block references with get_documentation. Reuse retrieved information; call list_examples or list_documentation only to discover unknown IDs. Use the returned model structure instead of guessing component or port names.
2. Call validate_model with {"model": …}. An accepted submission has http_status: 202 and a data object containing job_id and job_token.
3. Call get_job with both values. Respect retry_after; otherwise wait 1, 2, 4, then 8 seconds, keeping 8-second intervals thereafter. When the job is completed, call get_result. Keep the token private. Check http_status, success, diagnostics and termination: completed does not guarantee a successful calculation.
4. Take data.model from the successful validation result. Pass it to analyze_model, wait and retrieve that job's result. Resolve topology errors before simulation; document validation alone does not prove the model can run.
5. Pass the validated model to simulate_model, wait and retrieve its result. Inspect termination status, time and diagnostics before interpreting the series. Each submission returns its own job credentials.

Tool responses contain http_status, retry_after and data. The assistant should report status and errors, retain the model file alongside the results, and show only necessary selections instead of full numerical arrays.

Large dynamic results: client requirements

A dynamic simulation can return large time series for many diagram elements and variables. Finding values at requested times, extrema and events requires programmatic processing; placing the full JSON in the assistant's context does not replace working with files.

1. Before submission: verify that the client can receive tool responses in code without exposing large arrays to the model, save them to an accessible file, and subsequently read and process that file programmatically. If these capabilities are unavailable or unconfirmed, warn the user before starting a large simulation and suggest a client that supports them. Offer a smaller calculation only with an explanation of its effect on the requested result; never silently shorten the time interval or reduce resolution.
2. On retrieval: get_result returns full JSON, not a ready-made file. Save the received data directly from code before retention expires, without printing the full response or having the assistant rewrite arrays. Preserve original numerical data, variable and element identifiers, units, time coordinates, diagnostics and solver status. Verify that the file was written and can be read; save the normalized model separately.
3. During processing: load the file in code and select variables by identifier, values by time coordinate, extrema and events. If a requested time is absent from the output grid, explicitly state the nearest step selected or the interpolation method used. Expose file paths, actual simulated interval, point count, termination status, material diagnostics and a compact selection with units and identifiers to the assistant.
4. For presentation: build plots, tables and exports from saved data while preserving the full-resolution original. Display downsampling must retain relevant extrema and events. Do not rerun a simulation solely to change presentation.

Open the model in the editor

1. Save the model object from the validation result (data.model) as a UTF-8 .json file, for example two-mass.json. Do not save the entire tool response, job credentials or Markdown code fences as the model file.
2. Open the BGModeller editor. Save your current work first, then click Open in the toolbar and select the JSON file.
3. Inspect component parameters, initial conditions, connections and diagram layout. Use Analyze and Simulate to check and run it in the editor, then Save to keep your edits.

Model JSON preserves layout and settings, but does not embed simulation results. For large dynamic simulations, always save complete numerical results separately using the file-processing workflow. MCP does not automatically open your browser or save files on your computer; the client handles this. See results and files for the editor workflow.

Limits and troubleshooting

MCP and browser calculations share the public service's queue and per-IP allowances. A cloud assistant may use a shared outbound IP, so several users can share an allowance. MCP does not increase the available calculation capacity.

Call get_capabilities for the current data.limits and data.mcp_limits. The standard public configuration is:

• Busy or rate limited (429): wait for retry_after when provided and slow down polling. Validation and analysis also consume calculation allowances.
• Model error (422): read the diagnostics, fix the named components or connections and validate again.
• Job expired or not found (404): check that the ID and token belong together. Download results promptly; expired results cannot be recovered. Use your saved model to start a new calculation if needed.
• Connection lost during submission: the job may already be running. Do not automatically resubmit; if you received job credentials, check that job first.
• Tools unavailable: check the exact HTTPS URL, transport and enabled tools in your client. An MCP outage may leave the browser editor available.