Using SystemsLab from an AI Agent (MCP)

Connect an AI coding agent such as Claude Code, Codex or Cursor to an existing SystemsLab server. The agent can then submit experiments, follow their progress, read logs and artifacts, and query metrics on your behalf.

Let your agent do the setup

Give your agent the link to this page and your server's URL, and ask it to set up SystemsLab for you. For example:

Set up the SystemsLab MCP server for me, following the instructions at https://docs.iop.systems/guide/features/mcp. My server is https://systemslab.example.com.

Set Up the MCP Server

SystemsLab connects to agents through the Model Context Protocol (MCP). The agent runs the systemslab mcp command in the background and uses it to talk to your server, with your sign-in.

You need:

• The SystemsLab CLI installed on the machine running the agent.
• The URL of your SystemsLab server, for example https://systemslab.example.com.
• An account that can sign in to that server.

Add SystemsLab to Your Agent

Each example below passes your server's URL to systemslab mcp with --systemslab-url. Replace https://systemslab.example.com with your server's URL.

Register the server with claude mcp add:

claude mcp add systemslab -- \
    systemslab mcp --systemslab-url https://systemslab.example.com

Run claude mcp list to confirm that systemslab shows as connected. Or add it to a .mcp.json file in your project by hand:

{
  "mcpServers": {
    "systemslab": {
      "command": "systemslab",
      "args": ["mcp", "--systemslab-url", "https://systemslab.example.com"]
    }
  }
}

Register the server with codex mcp add:

codex mcp add systemslab -- \
    systemslab mcp --systemslab-url https://systemslab.example.com

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.systemslab]
command = "systemslab"
args = ["mcp", "--systemslab-url", "https://systemslab.example.com"]

Run codex mcp list to confirm it is registered.

Open Settings → Developer → Edit Config to open claude_desktop_config.json, and add a systemslab entry under mcpServers:

{
  "mcpServers": {
    "systemslab": {
      "command": "/usr/local/bin/systemslab",
      "args": ["mcp", "--systemslab-url", "https://systemslab.example.com"]
    }
  }
}

Claude Desktop does not use your shell's PATH, so give the full path to the CLI. Run which systemslab to find it; Homebrew installs it under /opt/homebrew/bin on Apple silicon Macs. Restart Claude Desktop after saving the file.

Add a systemslab entry to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in a project to share it with that project:

{
  "mcpServers": {
    "systemslab": {
      "command": "systemslab",
      "args": ["mcp", "--systemslab-url", "https://systemslab.example.com"]
    }
  }
}

Check that the server is enabled under Cursor Settings → MCP.

Add a systemslab entry to .vscode/mcp.json in your workspace. Note that VS Code uses a servers key rather than mcpServers:

{
  "servers": {
    "systemslab": {
      "type": "stdio",
      "command": "systemslab",
      "args": ["mcp", "--systemslab-url", "https://systemslab.example.com"]
    }
  }
}

Click Start above the entry in the editor, then select the SystemsLab tools from the tools picker in Copilot Chat's agent mode.

Any MCP client that can launch a stdio server works. Configure it to run:

systemslab mcp --systemslab-url https://systemslab.example.com

Most clients accept the same mcpServers JSON shape shown in the Cursor tab.

Sign In

If your server requires authentication, the agent asks you to sign in the first time it uses SystemsLab. It opens a browser window, or gives you a link to open if it cannot. Once you finish signing in, the agent carries on with your request. You can also ask it to sign in at any time, for example to switch accounts.

You can sign in from a terminal instead, before starting the agent. Run this on the same machine, user account and container that your agent runs systemslab mcp in:

systemslab login --systemslab-url https://systemslab.example.com

Over SSH or in a container without a browser, use the device flow, which prints a link and code to enter in any browser:

systemslab login --device --systemslab-url https://systemslab.example.com

Check the Connection

Start a new session in your agent and ask:

Which SystemsLab server and account are you using?

Check that the URL in the answer is the server you expect and, if it is shown, that the account is yours. Then try a read-only request:

List the hosts registered with SystemsLab and show which ones are idle.

What You Can Ask For

You do not need to know the names of the agent's SystemsLab tools; describe what you want and the agent picks the right ones. It can:

• Write, validate and submit experiments and sweeps, then wait for them to finish.
• Read job logs while a job runs or after it ends, and download artifacts.
• Look up past experiments and the specs they ran with.
• Query and compare collected metrics, and look for correlations between them.
• Group experiments into contexts, organize them in workspaces, and write up results as notebooks in the web UI.
• Show registered hosts and take a host out of scheduling.
• Check AWS capacity, prices and cost estimates, and approve or deny pending launches.

Because the agent can plan, run and analyze experiments end to end, you can hand it whole questions rather than single steps. For example:

Did last night's build regress Redis throughput compared with the last release? Run whatever experiments you need, and write up the answer in a notebook.

Find the point where p99 latency for our cache service starts to climb as client concurrency increases, and explain what limits it.

Our nightly benchmark has failed three nights in a row. Work out why and propose a fix.

Which EC2 instance type gives us the best throughput per dollar for this benchmark? Estimate the cost before launching anything.

Summarize what our past experiments tell us about the effect of enabling huge pages, and point out any results that disagree.

The agent acts with your permissions and can cancel experiments or drain hosts. Review your client's approval settings before allowing state-changing actions.

TIP

For an end-to-end example of an agent designing, running and analyzing a benchmark sweep, see Agent-Driven Analysis.

Troubleshooting

Symptom	What to do
The agent shows no SystemsLab tools	The agent could not start systemslab mcp. Check that the command is on the agent's PATH, or use its full path. Most agents show the error in their MCP settings or logs.
The agent says it cannot reach SystemsLab	Check that the --systemslab-url value in your MCP configuration is the address you use to open SystemsLab in your browser. If you were not signed in, ask the agent to sign in.
The agent reports that it is not signed in	Ask the agent to sign in, or run systemslab login --systemslab-url https://systemslab.example.com (add --device over SSH or in a container), then retry the request.
Experiments you can see in the web UI come back "not found"	The agent is talking to a different server. Ask the agent which server it is using and fix the --systemslab-url value in your MCP configuration.
A Jsonnet spec is rejected as invalid	Tell the agent that the spec is Jsonnet when you ask it to submit the file.