Connect your agent

The Metrana MCP server exposes the Query API as Model Context Protocol tools, so your own agent can list runs, compare them by their metrics, fetch curves and read the Metrana docs while it works. It is read-only: an agent can’t change anything in Metrana through it.

What you need

Setting	Value
Endpoint	`https://app.metrana.ai/api/mcp/v1` (Streamable HTTP). Self-hosted deployments use their own host.
OAuth client ID	`metrana-mcp`. A public client: there is no client secret.
Organization	Your organization’s slug: the first part of the path in the portal’s address bar, `app.metrana.ai/<organization>/...`. Required.
Workspace	Optional default workspace.
Project	Optional default project, within the default workspace.
Scope lock	Optional. `true` pins the connection to the default workspace and project: tools reject other ones, and `list_workspaces` / `list_projects` are unavailable. Both defaults are then required.

Your client sends the organization, workspace, project and scope lock either as request headers or as query parameters on the endpoint URL, whichever it supports:

Setting	Header	Query parameter
Organization	`X-Metrana-Organization`	`organization`
Workspace	`X-Metrana-Workspace`	`workspace`
Project	`X-Metrana-Project`	`project`
Scope lock	`X-Metrana-Scope-Lock`	`scope_lock`

For example, https://app.metrana.ai/api/mcp/v1?organization=my-org&workspace=my-workspace is a connection to my-org with my-workspace as its default. A setting given both ways must have the same value both times.

You sign in with your Metrana account. The first time your MCP client connects, it opens your browser at the Metrana sign-in page. Once you’ve signed in, the client keeps you signed in, and you only sign in again after 30 days without using the connection, or after you sign out of Metrana.

Your agent never sees a credential. The sign-in happens in your browser, and your MCP client keeps the token it gets, outside the model’s context: no tool takes it as an argument, and no response or error contains it. That token only works against the MCP server, never the Metrana APIs directly. Your agent’s environment doesn’t need METRANA_API_KEY, and you shouldn’t give it one.

One connection covers one organization. Your agent can read every workspace and project you can read in that organization: it finds them with the list_workspaces and list_projects tools and names the one it wants on each call. The organization itself can’t be changed from a tool call. If you belong to several organizations, add one connection per organization.

Defaults save your agent a step. Set the workspace and project to the ones you work in most, and tools read there unless the agent names another. Without them, the agent asks for or discovers the workspace and project first. To keep an agent to one project, for example in a shared repository’s .mcp.json, also set the scope lock.

Any role in a workspace lets you read it, viewer included.

Claude Code

Add the server from the command line. --scope user makes it available in every project on your machine:

claude mcp add --transport http --scope user --client-id metrana-mcp \
  metrana https://app.metrana.ai/api/mcp/v1 \
  --header "X-Metrana-Organization: my-org"

Add --header "X-Metrana-Workspace: my-workspace" and --header "X-Metrana-Project: my-project" to set defaults. Then run /mcp in Claude Code, pick metrana and sign in.

To share the connection with a team through a repository, put it in .mcp.json instead. Each person signs in as themselves; nothing secret goes in the file. Here the repository’s own workspace and project are the defaults:

{
  "mcpServers": {
    "metrana": {
      "type": "http",
      "url": "https://app.metrana.ai/api/mcp/v1",
      "oauth": {
        "clientId": "metrana-mcp"
      },
      "headers": {
        "X-Metrana-Organization": "my-org",
        "X-Metrana-Workspace": "my-workspace",
        "X-Metrana-Project": "my-project"
      }
    }
  }
}

Don’t add an Authorization header: Claude Code then skips the sign-in.

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project, then sign in from Cursor Settings → MCP:

{
  "mcpServers": {
    "metrana": {
      "url": "https://app.metrana.ai/api/mcp/v1",
      "auth": {
        "CLIENT_ID": "metrana-mcp"
      },
      "headers": {
        "X-Metrana-Organization": "my-org"
      }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in a workspace, or to your user configuration with MCP: Open User Configuration. VS Code opens the sign-in page when the server first starts:

{
  "servers": {
    "metrana": {
      "type": "http",
      "url": "https://app.metrana.ai/api/mcp/v1",
      "oauth": {
        "clientId": "metrana-mcp"
      },
      "headers": {
        "X-Metrana-Organization": "my-org"
      }
    }
  }
}

claude.ai

Custom connectors can’t send headers, so name your organization in the URL. In Settings → Connectors, choose Add custom connector and enter:

URL: https://app.metrana.ai/api/mcp/v1?organization=my-org, adding &workspace=… and &project=… for defaults.
Advanced settings → OAuth Client ID: metrana-mcp. Leave the client secret empty.

Then choose Connect and sign in. On Team and Enterprise plans, an owner adds the connector for the organization first, and each member then connects and signs in as themselves.

ChatGPT

With developer mode on (Settings → Security and login), create a connector for https://app.metrana.ai/api/mcp/v1?organization=my-org, with OAuth authentication and a user-defined OAuth client whose client ID is metrana-mcp, with no secret. Then sign in when ChatGPT asks.

Claude Desktop, Windsurf, Cline, Continue and JetBrains AI Assistant

These connect through the mcp-remote bridge, which runs the sign-in for them and needs Node.js. Each takes the same server entry:

{
  "mcpServers": {
    "metrana": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://app.metrana.ai/api/mcp/v1",
        "--static-oauth-client-info", "{\"client_id\": \"metrana-mcp\"}",
        "--header", "X-Metrana-Organization:my-org"
      ]
    }
  }
}

Write the header without a space after the colon: some clients mangle spaces inside args. The first time the client starts the server, mcp-remote opens your browser to sign in.

Client	Where the entry goes
Claude Desktop	Settings → Developer → Edit Config (`claude_desktop_config.json`); restart Claude Desktop afterwards.
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline	MCP Servers → Configure (`cline_mcp_settings.json`)
JetBrains AI Assistant	Settings → Tools → AI Assistant → Model Context Protocol (MCP), as JSON
Continue	`mcpServers` in `config.yaml`, in YAML form: `command: npx` and the same `args`

Other clients

Any MCP client that supports the Streamable HTTP transport and OAuth sign-in with a client ID you supply can connect directly: send the organization as a header, or in the endpoint URL if it can’t send headers. Any client that can run a local command can connect through mcp-remote, as above.

Limits

Limit	Value
Tool calls	60 per minute and 1,000 per hour, per user, across all connections. A refused call says when to retry.
Response size	64 KB per tool call. Larger results come back marked `truncated`, with a hint on how to narrow the request.
Listings	50 items by default, at most 200 per call; projects, runs and environments page with `offset`.
Series	10 series per call by default, at most 25; 200 points per series by default, at most 2,000.

Agents get the best results from the bucketed tools for long series. See Tools.

Troubleshooting

Error	Cause
HTTP 401, or the client says it needs to authenticate	You aren’t signed in, or your sign-in expired. Sign in again from the client (in Claude Code, `/mcp`).
The sign-in page says the redirect URI is invalid	The client isn’t one Metrana’s sign-in recognizes yet. Connect it through `mcp-remote` instead.
HTTP 400 naming a scope setting	The organization is missing; a header or query parameter is empty, malformed or repeated; or a setting given both ways has two different values.
“Metrana no longer accepts this connection’s sign-in…”	Your Metrana session ended, for example because you signed out. Sign in again from the client.
“You can’t read the requested workspace or project…”	Your role doesn’t cover what was asked for.
“You’re not a member of any workspace in organization ‘…’”	The organization isn’t the organization’s exact slug.
“Workspace ‘…’ doesn’t exist in this organization, or you can’t read it”	The workspace name is wrong, or you aren’t a member and it isn’t public.
“No workspace given…” / “No project given…”	The tool call named no workspace or project and the connection has no default for it. Agents recover by listing workspaces and projects.
“Project ‘…’ doesn’t exist in workspace ‘…’”	The project name is wrong for that workspace.
“Too many requests…”	You hit the rate limit; the message says how long to wait.

Signing out of Metrana ends your agents’ access within a few minutes.