Quickstart

Pick how you reach the server in production: hosted MCP at mcp.testrelic.ai (streamable HTTP, no local binary), npx with the published @testrelic/mcp package (stdio, any MCP client), or the Cursor marketplace plugin if you use Cursor. Optional sandbox paths (mock mode or a local git clone) are for evaluation and development only.

Purpose

Install or connect the TestRelic MCP server so your MCP host can use it (hosted URL or stdio), set a production MCP personal access token, then verify with tr_health.

Concept: stdio wiring

Install path vs typical setup depth

Horizontal bars compare how many discrete steps teams often budget before tr_health succeeds — illustrative counts for planning, not a guarantee. Bars assume production (hosted URL or npx with a token), not local sandbox builds.

Loading chart…

Cursor — marketplace

1. Open Cursor and search Settings → Plugins for testrelic-mcp.
2. Click Install. Cursor wires up the MCP server automatically from the bundled config; see the plugin’s mcp.json in testrelic-mcp-server for the exact wiring shipped to the marketplace.
3. Open the agent and ask something like "list my TestRelic projects" (or call tr_health).

The marketplace default boots in mock mode so you can explore every tool without an account or token.

For live org data in production, connect real data: create a personal access token (tr_mcp_*) at platform.testrelic.ai/settings/mcp-tokens, run npx @testrelic/mcp login (or set TESTRELIC_MCP_TOKEN=tr_mcp_…), and drop --mock-mode. See Authentication for details.

Manual mcp.json

Add a server entry to your client’s MCP configuration. Prefer hosted or npx + token for production.

Hosted (production)

Streamable HTTP MCP served at the production hostname (same pattern as mcp.json in the testrelic-mcp-server repo and the local preview scripts, with the production host):

mcp.json fragment

{
  "mcpServers": {
    "testrelic": {
      "url": "https://mcp.testrelic.ai/mcp"
    }
  }
}

Use your MCP client’s documented way to attach credentials if it requires a header or env for remote servers. Otherwise use the stdio tab so the process can read TESTRELIC_MCP_TOKEN or ~/.testrelic/token from Authentication.

npx (production stdio)

The package @testrelic/mcp is published on the public npm registry (pin a version for reproducible installs, e.g. 3.0.0). Production stdio config does not pass --mock-mode; supply your token via env (or run npx -y @testrelic/mcp@3.0.0 login once on the machine so ~/.testrelic/token exists):

mcp.json fragment

{
  "mcpServers": {
    "testrelic": {
      "command": "npx",
      "args": [
        "-y",
        "@testrelic/mcp@3.0.0",
        "--caps",
        "core,coverage,creation,healing,impact"
      ],
      "env": {
        "TESTRELIC_MCP_TOKEN": "<your tr_mcp_ token>"
      }
    }
  }
}

The MCP uses the production cloud API base https://platform.testrelic.ai/api/v1 by default unless you override TESTRELIC_CLOUD_URL. See Authentication.

Sandbox (non-production)

Use --mock-mode only for demos, CI smoke of the binary, or contributor workflows with no cloud token. Example with the same published package:

mcp.json fragment (mock mode)

{
  "mcpServers": {
    "testrelic": {
      "command": "npx",
      "args": [
        "-y",
        "@testrelic/mcp@3.0.0",
        "--caps",
        "core,coverage,creation,healing,impact",
        "--mock-mode"
      ]
    }
  }
}

Local git clone (contributors): from testrelic-mcp-server, after npm install and npm run build, point args at packages/mcp/dist/cli.js and set cwd to the repo root (absolute path). This is not the default production path.

Restart the MCP host app after saving. Run tr_health in the agent to confirm the server responds.

Mock mode vs production cloud

Mode	Use when
--mock-mode	Sandboxes only: learning the tool surface, demos, or CI smoke of the MCP binary. No outbound calls to TestRelic production APIs.
Production (token set, no mock flag)	Real repos, runs, journeys, and integrations resolved from your org in the TestRelic cloud.

Mock mode is the default for the zero-config / marketplace install. To connect real data:

1. Create a personal access token (tr_mcp_*) at platform.testrelic.ai/settings/mcp-tokens.
2. Run npx @testrelic/mcp login (or set TESTRELIC_MCP_TOKEN=tr_mcp_… in your client’s env).
3. Drop --mock-mode from your MCP server args.

See Authentication for creating and storing tr_mcp_… tokens.

Troubleshooting

Symptom	What to try
MCP host does not see the server	Restart the host after editing mcp.json; confirm you used the hosted URL, npx args, or contributor local paths consistently.
tr_health fails	Run from the agent after the server binary is reachable; check stderr from the MCP process in host logs.

FAQ

Should I start with mock mode?

Only for sandbox or contributor workflows. For production data, use the hosted URL or npx without `--mock-mode` and configure a token per Authentication.

Can I use both marketplace and manual mcp.json?

Use one path per host to avoid duplicate server definitions. Pick marketplace for Cursor if available; otherwise use hosted URL or npx stdio as in the tabs above.

What npm package name should I use?

The published package is `@testrelic/mcp` (not `@testrelic/mcp-server`). Install with `npx -y @testrelic/mcp@3.0.0` or another current version from the npm registry.

Optional: local mock API (contributors)

For development in testrelic-mcp-server, you can run a local mock HTTP API (npm run mock) and point the MCP at it with --mock-mode. Production users rely on the hosted endpoint or stdio against the real cloud instead.

Next steps

→ Authentication · Capabilities · Tools reference