Give an agent a live SysML v2 model, not a screenshot of one.

§01: WHAT IT IS, WHO IT'S FOR

The bridge between an agent and a headless SysML v2 repository

This server talks to any conformant SysML v2 API endpoint: the OMG reference pilot, or a commercial implementation. There is no CATIA Magic, no desktop tool, no GUI in the loop. If your systems model already lives in a headless SysML v2 API repository, and you want an AI agent to explore it, extend it, or restructure it directly, this is that bridge.

It is built for teams and individual engineers who want an agent working directly against a SysML v2 API project: exploring an existing model, authoring new elements and relationships, running parallel branches per agent session, or managing project lifecycle, all through the standard API rather than a proprietary desktop integration.

It is a companion to jgs-magic-sysmlv2-mcp, which drives a running Cameo instance instead. Use this server when the model lives in a headless SysML v2 API repository; use the Cameo bridge when it lives in a running Cameo desktop session.

§02: THE STAGED-COMMIT MODEL

Nothing reaches the API until you have seen what is about to be sent

Writes never touch the server directly. create_element, modify_element, delete_element, delete_subtree, create_relationship, move_element, and stage_batch all accumulate operations in an in-process buffer. The agent reviews the full staged batch and receives a confirm token bound to a fingerprint of exactly what it is about to commit. Only then does commit_changes post the batch as one atomic commit.

If anything new is staged after the review step, the token no longer matches and the commit is refused until the buffer is reviewed again. A commit can never include an operation the agent was not shown first.

1. Stage

   Create, modify, delete, relate, move, or batch elements. Every call lands in the session's own buffer, never on the server.

2. Review

   review_changes returns the full list of staged operations plus a confirm token bound to that exact buffer.

3. Commit or discard

   commit_changes with the confirm token posts one atomic commit. discard_changes drops the buffer with no trace if the agent changes its mind.

§03: THE TOOL SURFACE

35 tools across five areas

The full, generated list with parameters lives on the tool reference page. Here is the shape of it.

Rounding out the surface: ping and stats for infrastructure health and server metrics.

See the full 35-tool reference →

§04: SUPPORTED HOSTS

Any MCP client, Claude Code first

The server speaks the standard MCP stdio protocol, so any MCP-compatible client that can launch a local process can use it. It has been built and verified against Claude Code; other clients that follow the same protocol, such as Claude Desktop, should work the same way.

§05: INSTALL

Two pip installs, three environment variables

Requires Python 3.11 or later. The official SysML v2 API client is not on PyPI, so it is installed straight from its GitHub source.

pip install -e .
pip install "git+https://github.com/Systems-Modeling/SysML-v2-API-Python-Client.git"

See docs/install.md for the full prerequisites, a Docker recipe for running the OMG reference pilot locally, and how to verify the install.

§06: FIRST RUN

Point your MCP client at it, then say hello

Copy examples/mcp.json.example into your MCP client's config location (for example .mcp.json in a project root), drop the .example suffix, and fill in your endpoint, token, and project UUID:

{
  "mcpServers": {
    "jgs-sysmlv2": {
      "command": "python",
      "args": ["-m", "jgs_sysmlv2_api_mcp"],
      "env": {
        "SYSMLV2_BASE_URL": "https://your-sysmlv2-endpoint.example.com",
        "SYSMLV2_TOKEN": "YOUR_BEARER_TOKEN_HERE",
        "SYSMLV2_PROJECT": "YOUR_PROJECT_UUID_HERE"
      }
    }
  }
}

Restart your MCP client so it picks up the new server. Then ask your agent to call ping, the smallest tool in the registry. It does a live round trip to the endpoint's commit list and reports whether the connection is healthy:

{"up": true, "api_version": null, "commit_count": 0}

If ping fails, recheck SYSMLV2_BASE_URL and SYSMLV2_TOKEN first: nearly every install problem traces back to one of those two. From there, docs/usage.md walks four full workflows: exploring a model you did not build, authoring and committing a change, running one branch per agent session, and managing a project's lifecycle.

§07: DESIGN NOTES

Three ground-truth facts that shape the code

Discovered by a day-one spike against the pilot, these decisions run through the implementation: