MCP tools

The Scout Trails MCP server offers twelve read-only tools. Your assistant chooses and calls them for you; this page describes what each one accepts and returns so you know what to ask for and how to read the answers. Every tool reads only your organization’s data.

How results look

• Each tool returns one JSON object, both as structured content and as the same JSON in a text block.
• Timestamps are RFC 3339 strings in UTC.
• A list with nothing in it may come back as null rather than [].
• When a tool fails, the call returns a JSON-RPC error (code -32603) whose message starts with the tool name, for example get_session: session "abc" not found or activity: unsupported granularity "2h" (want one of: 1m, 5m, 15m, 1h, 1d). Calling a tool that does not exist returns code -32602.

Time windows

The insight tools (activity, top_tools, outlier_sessions, cost_summary, risk_feed, external_domains) look back from the current time over a window:

• Write it as a number and unit: 30m, 6h, 24h, 7d, 90d. Units are s, m, h and d. s, m and h can be combined, as in 1h30m; d must be used on its own, as in 7d. Weeks (w) are not accepted; use 7d.
• The default is 24h. A window shorter than one minute is raised to 1m; a window longer than 90 days is reduced to 90d.
• The response echoes the window in hours, minutes and seconds: 24h comes back as "24h0m0s" and 7d as "168h0m0s".

Limits and pagination

limit inputs are clamped to 1–200; a missing, zero or negative limit uses the tool’s default. list_sessions and list_tool_calls return a next_cursor when more rows exist; pass it back as cursor, with the same filters, to get the next page.

Actor and team filters

actor takes one actor telemetry id, and team takes a list of them. Telemetry ids are listed in the Telemetry id column of Manage > Actors & ingest keys and returned as actor_id. A dashboard team name does not work as team; pass the telemetry ids of the team’s actors.

ping

Checks the connection. Takes no inputs.

{"ok": true, "version": "0.1.0"}

whoami

Returns the organization the API key belongs to. Takes no inputs.

{"tenant_id": "ExampleTenantId_ExampleTenantId_ExampleTena"}

tenant_id matches the value under Telemetry tenant on Manage > Organization.

list_sessions

Lists sessions, most recent activity first.

The time, agent, actor and team filters select tool calls, and each session is summarised from the matching calls.

{
  "sessions": [
    {
      "session_id": "5e551011-0000-4000-8000-000000000001",
      "tenant_id": "ExampleTenantId_ExampleTenantId_ExampleTena",
      "actor_id": "Q2xhdWRlQ29kZS1sYXB0b3AtMDAwMDAwMDAwMDAwMDAw",
      "agent_system": "claude-code",
      "first_seen": "2026-09-24T15:57:39.647Z",
      "last_seen": "2026-09-25T15:27:56.67Z",
      "tool_calls": 68,
      "duration_ms": 84617023
    }
  ],
  "next_cursor": "MTc5MDM1MDA3NjY3MDAwMDAwMHwwMjhlYTQxMS0yYThiLTQ0ZTctYTUwOS1mYzZjYTY0MjRiN2Y"
}

get_session

Returns one session with everything recorded in it.

{
  "session": {
    "session_id": "341e6a93-2505-40d4-8bb2-03286d6b3360",
    "tenant_id": "ExampleTenantId_ExampleTenantId_ExampleTena",
    "actor_id": "Q2xhdWRlQ29kZS1sYXB0b3AtMDAwMDAwMDAwMDAwMDAw",
    "agent_system": "claude-code",
    "first_seen": "2026-09-23T17:57:00.215Z",
    "last_seen": "2026-09-23T17:57:00.215Z",
    "tool_calls": 1,
    "duration_ms": 0
  },
  "tool_calls": [ { "id": "f313eb76-9727-40ef-ba69-6d03dbdbb515", "tool_name": "Bash", "outcome": "ok", "...": "..." } ],
  "llm_calls": [
    {
      "id": "f23ace2f-1130-4c0e-8a98-a4cbc961125f",
      "timestamp": "2026-09-23T17:56:59.548Z",
      "session_id": "341e6a93-2505-40d4-8bb2-03286d6b3360",
      "prompt_id": "2eeec48f-78b3-49ea-85cf-527fff0e261c",
      "agent_system": "claude-code",
      "model": "claude-opus-5-5",
      "duration_ms": 3194,
      "input_tokens": 2,
      "output_tokens": 82,
      "cache_read_tokens": 10704,
      "cache_creation_tokens": 24041,
      "cost_usd": 0.1961168,
      "is_error": false,
      "error_type": "",
      "error_message": ""
    }
  ],
  "risk_flags": [],
  "external_domains": []
}

Each list holds at most 500 entries; use list_tool_calls with session_id to page through a longer session. An unknown session returns the error get_session: session "<id>" not found.

list_tool_calls

Lists individual tool calls, newest first.

Returns {"tool_calls": [...], "next_cursor": "..."}, each entry shaped as in get_tool_call.

get_tool_call

Returns one tool call by its id.

{
  "id": "f313eb76-9727-40ef-ba69-6d03dbdbb515",
  "tenant_id": "ExampleTenantId_ExampleTenantId_ExampleTena",
  "actor_id": "Q2xhdWRlQ29kZS1sYXB0b3AtMDAwMDAwMDAwMDAwMDAw",
  "timestamp": "2026-09-23T17:57:00.215Z",
  "session_id": "341e6a93-2505-40d4-8bb2-03286d6b3360",
  "prompt_id": "2eeec48f-78b3-49ea-85cf-527fff0e261c",
  "agent_system": "claude-code",
  "agent_version": "2.1.280",
  "model": "",
  "tool_name": "Bash",
  "tool_type": "builtin",
  "category": "code_exec",
  "tool_call_id": "toolu_01XrWPS2d9PQcB3kWyX1XNMu",
  "tool_use_id": "toolu_01XrWPS2d9PQcB3kWyX1XNMu",
  "arguments": "{\"bash_command\":\"echo\",\"full_command\":\"echo hello\",\"description\":\"Print a string\"}",
  "result": "",
  "result_size_bytes": 12,
  "duration_ms": 517,
  "success": true,
  "outcome": "ok",
  "error_type": "",
  "error_message": "",
  "decision": "",
  "decision_source": "",
  "mcp_server_name": "",
  "mcp_server_scope": ""
}

Empty values are returned as "". An unknown id returns the error get_tool_call: tool_call "<id>" not found.

activity

Tool calls, model calls and model cost over time.

{
  "window": "720h0m0s",
  "granularity": "1d",
  "buckets": [
    {"bucket_start": "2026-09-15T00:00:00Z", "tool_calls": 8, "llm_calls": 8, "cost_usd": 0.343967},
    {"bucket_start": "2026-09-16T00:00:00Z", "tool_calls": 24, "llm_calls": 24, "cost_usd": 1.031901}
  ]
}

Buckets are labelled with their start time in UTC, oldest first. Buckets with no activity are omitted.

top_tools

The most-used tools in the window.

{
  "window": "168h0m0s",
  "tools": [
    {"name": "Read", "count": 266, "ran": 266, "success_rate": 1, "total_cost": 7.759917},
    {"name": "Bash", "count": 120, "ran": 112, "success_rate": 0.95, "total_cost": 5.10422}
  ]
}

outlier_sessions

Sessions in the window ranked by how unusual they are, measured by tool-call count and model cost.

{
  "window": "720h0m0s",
  "sessions": [
    {"session_id": "5e551011-0000-4000-8000-000000000001", "tool_calls": 68, "cost_usd": 6.997629, "outlier_score": 11.05},
    {"session_id": "5a0c9e71-03d2-4c1e-9f0b-6a1f2e7d8c44", "tool_calls": 260, "cost_usd": 0, "outlier_score": 10.85}
  ]
}

outlier_score is the number of standard deviations the session sits above the window’s average, on tool calls or on cost, whichever is higher. The list is sorted by score and always returns up to limit sessions, so the lowest entries may not be outliers. Scores are 0 when the window has fewer than two sessions.

cost_summary

Model cost and token totals, with a breakdown.

{
  "window": "720h0m0s",
  "group_by": "model",
  "summary": {"cost_usd": 10.9496248, "calls": 163, "input_tokens": 450394, "output_tokens": 129679},
  "breakdown": [
    {"key": "claude-opus-4-7", "cost_usd": 6.997629, "calls": 81, "input_tokens": 8706, "output_tokens": 51182},
    {"key": "claude-opus-4-6", "cost_usd": 1.72596, "calls": 40, "input_tokens": 269472, "output_tokens": 41488}
  ]
}

calls counts model calls. Cost is what the agents report, in US dollars; it is 0 for agents that do not report cost. The breakdown holds up to 200 rows, highest cost first.

risk_feed

Risk flags raised on tool calls, newest first, with a severity for each.

{
  "window": "24h0m0s",
  "count_by_severity": [
    {"severity": "high", "count": 2},
    {"severity": "medium", "count": 1}
  ],
  "events": [
    {
      "timestamp": "2026-10-05T14:02:11.031Z",
      "session_id": "5e551011-0000-4000-8000-000000000001",
      "tool_call_id": "toolu_01AbCdEfGhIjKlMnOpQrStUv",
      "tool_name": "Bash",
      "flag": "destructive_operation",
      "severity": "high",
      "evidence": "rm recursive/force"
    }
  ]
}

count_by_severity lists severities from high to low and covers the whole window with the same session_id and severity filters, not only the events returned. events holds up to 200 flags. evidence is a short description of what matched: the path for sensitive_path, the kind of command for destructive_operation, or the kind of credential and its first few characters for credential_detected. tool_call_id is the agent’s own id for the call; to see the full call, run get_session for the session and find the tool call with the same tool_call_id.

external_domains

Hosts found in your agents’ tool-call arguments (fetched URLs, curl and wget targets, and URL arguments of MCP tools), most-referenced first.

{
  "window": "720h0m0s",
  "domains": [
    {"host": "github.com", "count": 12, "first_seen": "2026-09-15T16:21:24.573749Z", "last_seen": "2026-09-22T13:54:48.385442Z"}
  ]
}

count is the number of references to the host, and first_seen and last_seen bound them within the window. The list holds up to 200 hosts.

In this section

• MCP overview
• Setup