MCP setup

This page connects an MCP client to the Scout Trails MCP server at https://mcp.scoutmonitoring.io/mcp. Any client that supports remote MCP servers over streamable HTTP with a custom Authorization header can connect. Recipes follow for Claude Code, Codex CLI and Cursor.

Before you start

1. Create an API key under Manage > API keys in the dashboard and copy it. The key starts with wb_api_ and is shown only once. See Creating a key.

2. Put the key in an environment variable in the shell that starts your client:

   export TRAILS_API_KEY="wb_api_..."
   

   Add the line to your shell profile (~/.zshrc, ~/.bashrc) to keep it across sessions.

An ingest key does not work for MCP. If you only have the key from your agent’s telemetry setup, create an API key.

Claude Code

Add the server with claude mcp add. The server name, trails here, is the name Claude Code shows for it; pick any name you like.

claude mcp add --transport http --scope user trails \
  https://mcp.scoutmonitoring.io/mcp \
  --header "Authorization: Bearer $TRAILS_API_KEY"

• --scope user makes the server available in every project. Leave it out to add the server to the current project only, for your user.
• The shell expands $TRAILS_API_KEY when you run the command, so the key value is stored in your Claude Code configuration.

To share the server with your team through a project’s .mcp.json without committing a key, add this entry and have each person set TRAILS_API_KEY in their own environment. Claude Code expands ${TRAILS_API_KEY} when it starts.

{
  "mcpServers": {
    "trails": {
      "type": "http",
      "url": "https://mcp.scoutmonitoring.io/mcp",
      "headers": {
        "Authorization": "Bearer ${TRAILS_API_KEY}"
      }
    }
  }
}

Check the connection:

claude mcp list

The trails entry shows ✔ Connected. Inside a Claude Code session, /mcp lists the server and its tools.

Codex CLI

Add the server to ~/.codex/config.toml. bearer_token_env_var names the environment variable that holds the key; Codex sends it as Authorization: Bearer <key>.

[mcp_servers.trails]
url = "https://mcp.scoutmonitoring.io/mcp"
bearer_token_env_var = "TRAILS_API_KEY"

Or add the same entry from the command line:

codex mcp add trails --url https://mcp.scoutmonitoring.io/mcp \
  --bearer-token-env-var TRAILS_API_KEY

Check the connection with codex mcp list, or type /mcp inside a Codex session.

If Codex also sends telemetry to Scout Trails, the MCP entry and the telemetry exporter use different keys: an API key here and an actor’s ingest key in the [otel] section. See Codex CLI.

Cursor

Add the server to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json in a project. Cursor expands ${env:TRAILS_API_KEY} from your environment.

{
  "mcpServers": {
    "trails": {
      "url": "https://mcp.scoutmonitoring.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TRAILS_API_KEY}"
      }
    }
  }
}

Open Cursor’s MCP settings to confirm the server is enabled and lists its tools.

Other clients

Configure the client with:

A client that can only connect to remote servers through OAuth, without custom headers, cannot connect.

To check a key without a client, call the whoami tool directly:

curl -s https://mcp.scoutmonitoring.io/mcp \
  -H "Authorization: Bearer $TRAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

A working key returns a result containing your organization’s tenant_id, the same value shown under Telemetry tenant on Manage > Organization.

Try it

Ask your assistant:

• “Use Trails to check you can reach it.” (ping, whoami)
• “List my five most recent sessions in Trails.”
• “Show every tool call in session 5e551011-0000-4000-8000-000000000001 that failed or was rejected.”
• “Which tools did my agents use most in the last 7 days, and how often did they fail?”
• “What did we spend on models in the last 30 days, broken down by model?”
• “Are there any high-severity risk flags from the last 24 hours? Show the evidence.”
• “Which external hosts did our agents contact this week?”
• “Find this week’s outlier sessions and summarise what happened in the top one.”

Troubleshooting

In this section

• MCP overview
• Tools