Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.traversal.com/llms.txt

Use this file to discover all available pages before exploring further.

The Traversal MCP server lets any compatible AI client — Claude Code, Cursor, Claude Desktop, and others — run investigations, ask follow-ups, and retrieve results using the Model Context Protocol. It uses the streamable-http transport with API key authentication. But it’s more than a remote command. Over MCP, Traversal acts as a peer agent your local agent works alongside: your agent handles what’s local — your code, your terminal, your tools — while Traversal investigates across your whole production stack, and the two hand work back and forth until the incident is understood. Endpoint: https://api.prod.traversal.com/mcp/ For BYOC deployments, use your organization’s API URL + /mcp/.

​
Agent-to-agent mode

When Traversal is called from another agent, it runs in Lightning mode — a fast investigation path built for the rapid back-and-forth of agent collaboration. A first pass typically returns in 30 seconds to 2 minutes, fast enough for a real back-and-forth between your agent and Traversal rather than a single round trip. Your agent can always follow up to go deeper. The collaboration runs in both directions:

Your agent → Traversal

Your agent sends Traversal the problem — along with what it can do locally (your repo, kubectl, your other tools). Traversal investigates across your metrics, logs, traces, deployments, and topology — the production-wide view your local agent can’t see on its own.

Traversal → your agent

Traversal hands back specific, executable next steps — check src/checkout/handler.go:142 or run kubectl logs -n prod checkout-service-xyz. Your agent runs them locally and feeds the results back — no orchestration on your part.
The payoff: your local agent’s strengths — kubectl, SSH, repository access, your other MCP tools — combine with Traversal’s cross-stack investigation. Neither agent could close the loop alone.

​
The collaboration loop

From your side, you just talk to your agent the way you always do — it handles the rest:
1

Your agent calls `investigate`

It sends Traversal the problem, what it can access locally, and how focused to stay.
2

Traversal investigates

A Lightning-mode investigation runs across your observability stack and returns findings plus next steps your agent can execute.
3

Your agent acts locally

It reads the file, runs the command, or queries a tool only it has access to.
4

Your agent calls `follow_up`

It passes the new evidence back, using the session_id from the first call. Traversal folds it in and refines the diagnosis.
5

Repeat until resolved

Follow up as many times as you need — each call builds on the same investigation context.

​
You don’t drive it — your agent does

You don’t call Traversal directly or craft a special request. Just describe the problem to your AI agent the way you normally would; it decides when to bring Traversal in and passes along the context that sharpens an investigation:
  • What it can access locally — your codebase, kubectl, your other tools — so Traversal can hand back steps your agent can actually run.
  • How focused to be — a tight look at one service, or a broad sweep across many.
  • The affected services and time window, so Traversal targets the right place first.

​
Authentication

Generate an API key in the Traversal web app under Settings > API keys. The key is shown once — copy it immediately. Pass it in the Authorization header: 
Authorization: Bearer trv_ak_...

​
Setup

The config is the same across clients — an endpoint URL and an Authorization header. Find your client below.
Open Settings > Developer > Edit Config and add:
{
  "mcpServers": {
    "Traversal": {
      "type": "http",
      "url": "https://api.prod.traversal.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Restart Claude Desktop after saving.
claude mcp add traversal \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -- https://api.prod.traversal.com/mcp/
Add to .cursor/mcp.json in your project root or global settings:
{
  "mcpServers": {
    "Traversal": {
      "url": "https://api.prod.traversal.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Add to your opencode.json config:
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "traversal": {
      "type": "remote",
      "url": "https://api.prod.traversal.com/mcp/",
      "oauth": false,
      "timeout": 300000,
      "headers": {
        "Authorization": "Bearer {env:TRAVERSAL_API_KEY}"
      }
    }
  }
}
Set the TRAVERSAL_API_KEY environment variable with your API key before launching OpenCode.
Any client supporting the streamable-http transport can connect (ChatGPT, Windsurf, VS Code, etc.). Configure it with the endpoint URL and an Authorization: Bearer header containing your API key.

​
Available tools

ToolDescription
investigateRun a fast first-pass investigation (typically 30s–2min). The agent passes the incident, what it can access, and how focused to be.
follow_upContinue an investigation using its session_id — drill into findings, verify a hypothesis, or feed back evidence your agent gathered locally.
get_investigationGet the status and report for an investigation, with a ui_url link to the web app.
list_investigationsList recent investigations for your organization.
product_feedbackSend feedback about the MCP experience to the Traversal team.
A single investigate call is a first pass. Following up at least once — to drill into findings, verify hypotheses, or return what your agent found locally — is where agent-to-agent mode earns its keep.

​
FAQ

MCP calls run in Lightning mode, optimized to return a useful first pass in roughly 30s–2min so your agent can keep moving. The web app can run longer, deeper investigations; over MCP, that depth comes from follow-ups instead.
No. Traversal is always read-only and never touches your systems. In agent-to-agent mode it suggests next steps — a command to run, a file to check — and your local agent decides whether to execute them, with its own permissions and access. The two stay cleanly separated: Traversal investigates, your agent acts.
Verify your API key is correct and hasn’t been revoked. If you recently regenerated it, update your client configuration.
Broad investigations can take up to 2 minutes. Try a surgical investigation first and use follow_up to expand scope.
Call get_investigation — the response includes a ui_url link to the full investigation in the Traversal web app.