Use InstantML with agents

Connect an MCP-compatible agent to InstantML so it can inspect runs, fetch bounded metric series, compare selected runs, export evidence, and draft reports through the same API your SDK and dashboard use.

Tool summary

The MCP server exposes two groups of tools. Run tools read run, metric, and artifact data; report tools create and manage reports.

Run tools

Report tools

Prerequisites

• An InstantML API key with export:read for run-analysis tools.
• A workspace-scoped key when the agent should create or update reports across the workspace.
• Node.js only when your client needs the mcp-remote bridge shown below.

Connect to the hosted server

Use the hosted MCP server for the fastest setup:

https://mcp.instantml.ai/mcp

You do not need to deploy your own InstantML backend, clone the InstantML repository, or keep a local MCP process running. Your agent connects over Streamable HTTP and sends an InstantML API key in the Authorization header.

Set up from the dashboard

1. Open the InstantML dashboard and go to Agent in the nav rail.
2. In the Connect panel, pick Browser sign-in (default, read-only) or API key. For a key, create an Agent MCP key in Workspace settings → API first — the snippet fills it in for you.
3. Copy the setup snippet for Claude Code, Codex, Cursor, VS Code, or a local bridge.
4. Restart or reconnect the client, then ask it to list your latest InstantML runs. The panel's activity line confirms the first request.

Use the manual snippets below when setting up an agent before opening the dashboard. See the Agent tab for the dashboard walkthrough.

Browser sign-in (OAuth)

OAuth-capable clients can connect by URL alone and sign in through the browser instead of pasting a key. In the Agent tab's Connect panel, choose Browser sign-in and copy the tokenless snippet, for example:

claude mcp add --transport http instantml "https://mcp.instantml.ai/mcp?org_id=<workspace-id>"

On first connect the client discovers the InstantML authorization server, opens a browser for you to approve access for your workspace, and receives a short-lived token — there is no key to copy, rotate, or commit. Clients without OAuth support keep using the API-key snippets below.

Browser sign-in is scoped to the workspace selected in the dashboard when you copy the snippet. If you belong to multiple workspaces, add one MCP server per workspace rather than using one connection for all of them.

Connect Claude Code

Register the hosted MCP server from your terminal:

claude mcp add --transport http instantml https://mcp.instantml.ai/mcp \
  --header "Authorization: Bearer instantml_..."

Add --scope user to make the server available across all Claude Code projects. After adding the server, run /mcp inside Claude Code to confirm the server is connected.

Connect Codex

Export your InstantML API key:

export INSTANTML_API_KEY=instantml_...

Then add the hosted server to ~/.codex/config.toml:

[mcp_servers.instantml]
url = "https://mcp.instantml.ai/mcp"
bearer_token_env_var = "INSTANTML_API_KEY"

Connect Cursor

Open Cursor Settings, go to Tools and MCP, then add a custom MCP server:

{
  "mcpServers": {
    "instantml": {
      "transport": "http",
      "url": "https://mcp.instantml.ai/mcp",
      "headers": {
        "Authorization": "Bearer instantml_...",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Restart Cursor after saving the config.

Connect VS Code

Create or update .vscode/mcp.json in your workspace:

{
  "servers": {
    "instantml": {
      "type": "http",
      "url": "https://mcp.instantml.ai/mcp",
      "headers": {
        "Authorization": "Bearer instantml_..."
      }
    }
  }
}

Open the Command Palette and run MCP: List Servers, then start the InstantML server.

Bridge Claude Desktop and local-only clients

Some clients launch local stdio servers but do not yet support authenticated remote MCP headers. Use mcp-remote as a local bridge:

{
  "mcpServers": {
    "instantml": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.instantml.ai/mcp",
        "--header",
        "Authorization:${INSTANTML_MCP_AUTH_HEADER}"
      ],
      "env": {
        "INSTANTML_MCP_AUTH_HEADER": "Bearer instantml_..."
      }
    }
  }
}

Restart the client after saving the config. The bridge runs locally and forwards requests to the hosted MCP server with your bearer token.

Configure other MCP clients

Use these connection settings:

If your client only accepts a command, use:

INSTANTML_MCP_AUTH_HEADER="Bearer instantml_..." \
npx -y mcp-remote https://mcp.instantml.ai/mcp \
  --header "Authorization:${INSTANTML_MCP_AUTH_HEADER}"

Verify the connection

Ask your agent:

List my InstantML projects and show the latest five runs.

The agent should discover the InstantML tools, call tracker.list_projects if it needs to choose a project, and then call tracker.list_runs.

Guide the agent's workflow

Ask the agent to narrow candidates before fetching detailed data:

Find the best finished cartpole runs tagged baseline, compare the top five by
eval/return_mean, and summarize the config differences.

The agent should usually call:

1. tracker.list_projects if the project name is unknown.
2. tracker.list_runs with project, query, sort_by: "metric-best", and metric_key.
3. tracker.list_metrics if the metric key is unknown.
4. tracker.get_metric_series_batch for bounded curves across the selected run IDs.
5. tracker.compare_runs after narrowing to at most 50 run IDs.
6. tracker.export_runs when you need portable evidence for a notebook or spreadsheet.

Search with run queries

tracker.list_runs uses the same run search language as the dashboard:

tag:baseline status:finished
notes:"reward stability" -tag:debug
(tag:baseline OR tag:candidate) config:lr
re:/seed-(13|14)/

Bare text, such as seed 13 reward, searches name, tags, notes, config, metadata, status, project, and ID as implicit AND terms.

Stay inside MCP limits

InstantML keeps MCP reads bounded:

• Run summary pages are capped at 1,000 rows.
• Batched metric series accepts up to 2,000 run IDs and caps total returned points.
• Selected-run comparison accepts up to 50 run IDs and 5,000 compare rows.
• Workspace-view data accepts up to 100 run IDs, 50 panels, 500 points per series, and 50,000 total metric points.
• Selected export accepts up to 100 exact run IDs.

If an agent needs broad project analysis, ask it to start with summaries and metric aggregates, then fetch detailed series only for the candidate runs it selects.

Troubleshoot the connection

Run the server locally (preview fallback)

During internal development, you can run the MCP server from a repository checkout instead of using the hosted endpoint:

{
  "mcpServers": {
    "instantml": {
      "command": "node",
      "args": ["/path/to/instantml/tools/mcp-server.mjs"],
      "env": {
        "INSTANTML_API_URL": "https://api.instantml.ai",
        "INSTANTML_WEB_URL": "https://instantml.ai",
        "INSTANTML_API_KEY": "instantml_..."
      }
    }
  }
}

The local fallback runs next to the agent over stdio. INSTANTML_API_URL defaults to https://api.instantml.ai, and INSTANTML_WEB_URL defaults to https://instantml.ai for report share links, so consumers normally only need to set INSTANTML_API_KEY.

Next steps

• Create and manage API keys
• Build reports in the dashboard
• Query runs, metrics, and objects from Python
• API authentication and scopes
• Reports API reference