Skip to main content

Client setup

Below is the configuration for popular programs. They all use the same address:

https://api.metriox.com/mcp

Tokens are minted in the app: Project settings and then MCP tokens. If you have not minted one yet, here is how. Replace mcp_YOUR_TOKEN below with the real value.

Keep the token out of files that end up in git

Some clients can read the token from an environment variable or prompt for it at startup. Where that is possible, it is shown first: it is safer, especially for files like .vscode/mcp.json and .cursor/mcp.json that are usually committed.

Claude Code​

One command in the terminal:

claude mcp add --transport http metriox https://api.metriox.com/mcp --header "Authorization: Bearer mcp_YOUR_TOKEN"

Check that the server connected:

claude mcp list

Codex CLI​

Open ~/.codex/config.toml and add a section. The preferred form keeps the token in an environment variable:

[mcp_servers.metriox]
url = "https://api.metriox.com/mcp"
bearer_token_env_var = "METRIOX_MCP_TOKEN"

Then export the variable (in ~/.zshrc, ~/.bashrc or a secret manager):

export METRIOX_MCP_TOKEN="mcp_YOUR_TOKEN"

The alternative is the header directly in the config, if an environment variable is inconvenient:

[mcp_servers.metriox]
url = "https://api.metriox.com/mcp"
http_headers = { Authorization = "Bearer mcp_YOUR_TOKEN" }

There is a third option, env_http_headers, which maps a header name to the environment variable to read its value from.

If analytics queries over long ranges do not finish inside the timeout, raise the limits (the defaults are 10 and 60 seconds):

startup_timeout_sec = 20
tool_timeout_sec = 120

GitHub Copilot CLI​

File ~/.copilot/mcp-config.json (for every project), or .mcp.json / .github/mcp.json at the repository root:

{
  "mcpServers": {
    "metriox": {
      "type": "http",
      "url": "https://api.metriox.com/mcp",
      "headers": { "Authorization": "Bearer mcp_YOUR_TOKEN" },
      "tools": ["*"]
    }
  }
}

type must be http. The value sse is the legacy transport and will not work with Metriox.

Known Copilot CLI bug

Copilot CLI requests /.well-known/oauth-authorization-server even when a token header is already configured and, finding no OAuth configuration, discards the header, so the connection fails on authorization. This is a client bug, not a Metriox one: github/copilot-cli#3100 (open at the time of writing).

Workaround: run /mcp enable inside the Copilot session, which bypasses the probe and applies the header.

VS Code (Copilot Chat)​

Requires VS Code 1.101 or newer. File .vscode/mcp.json in the project, or your user mcp.json.

This file is usually committed, so the token is requested at startup rather than stored in it:

{
  "servers": {
    "metriox": {
      "type": "http",
      "url": "https://api.metriox.com/mcp",
      "headers": { "Authorization": "Bearer ${input:metriox_token}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "metriox_token",
      "description": "Metriox MCP token",
      "password": true
    }
  ]
}

VS Code asks for the token the first time it starts the server and keeps it in its own secret storage; only the ${input:metriox_token} reference stays in the file.

Note that the top-level key here is servers, not mcpServers as it is for Copilot CLI and Cursor.

Cursor​

File ~/.cursor/mcp.json (globally) or .cursor/mcp.json (per project). Cursor interpolates ${env:…} in both url and headers, so keep the token in an environment variable:

{
  "mcpServers": {
    "metriox": {
      "url": "https://api.metriox.com/mcp",
      "headers": { "Authorization": "Bearer ${env:METRIOX_MCP_TOKEN}" }
    }
  }
}

claude.ai, Claude Desktop and mobile​

Connects as a custom connector:

  1. Open Settings, then Connectors, then Add custom connector
  2. URL: https://api.metriox.com/mcp
  3. Authentication: choose None
  4. Expand Request headers and add a header:
    • name: authorization
    • value: Bearer mcp_YOUR_TOKEN

The header value is forwarded verbatim, so the word Bearer and the space after it are required.

Not available to every organization

Passing a token through Request headers is in beta and is not open to all organizations. If the add-connector dialog has no Request headers section, your organization does not have this capability yet and Metriox cannot be connected to claude.ai this way. The clients listed above (Claude Code, Codex, Copilot, VS Code, Cursor) work without that restriction.

Authorization settings cannot be changed after adding

A connector's headers and authorization settings are not editable. To replace the token, delete the connector and add it again with the new value.

If it does not connect​

401 Unauthorized. The token is revoked, expired, or was copied incompletely. Check in MCP tokens that it is active, and that the header carries the Bearer prefix including the space.

403 Forbidden. The token is valid, but the person who minted it no longer has the necessary rights on the project: rights are checked on every request. Check that member's role.

The agent cannot find a tool. Thirty-one tools are available, listed on the Tools page. An agent can change dashboards and author broadcasts.

A tool returns "bot not found". The bot id must belong to the same project the token was minted for. Get valid ids from metriox_list_bots.

429 Too Many Requests. The rate limit fired. It is counted per token, so an agent does not interfere with your own work in the browser. Ask the agent to make fewer requests, or to use wider intervals.

Copilot CLI fails on authorization. See the known bug above.

Commands and file paths were checked against each vendor's own documentation. Clients change: if a command does not work, check your program's official documentation.

Last updated on