> ## 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.

# MCP

> Run Traversal from Claude, Cursor, and other AI clients — and let your local agent and Traversal investigate together.

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](https://modelcontextprotocol.io/). 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 [single-tenant SaaS](/architecture/single-tenant-saas) or [BYOC](/architecture/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:

<CardGroup cols={2}>
  <Card title="Your agent → Traversal" icon="arrow-right">
    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.
  </Card>

  <Card title="Traversal → your agent" icon="arrow-left">
    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.
  </Card>
</CardGroup>

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:

<Steps>
  <Step title="Your agent calls `investigate`">
    It sends Traversal the problem, what it can access locally, and how focused to stay.
  </Step>

  <Step title="Traversal investigates">
    A Lightning-mode investigation runs across your observability stack and returns findings plus next steps your agent can execute.
  </Step>

  <Step title="Your agent acts locally">
    It reads the file, runs the command, or queries a tool only it has access to.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Repeat until resolved">
    Follow up as many times as you need — each call builds on the same investigation context.
  </Step>
</Steps>

### 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](https://app.traversal.com/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.

<AccordionGroup>
  <Accordion title="Claude Desktop">
    Open **Settings > Developer > Edit Config** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "Traversal": {
          "type": "http",
          "url": "https://api.prod.traversal.com/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Accordion>

  <Accordion title="Claude Code">
    ```bash theme={null}
    claude mcp add traversal \
      --transport http \
      --header "Authorization: Bearer YOUR_API_KEY" \
      -- https://api.prod.traversal.com/mcp/
    ```
  </Accordion>

  <Accordion title="Cursor">
    Add to `.cursor/mcp.json` in your project root or global settings:

    ```json theme={null}
    {
      "mcpServers": {
        "Traversal": {
          "url": "https://api.prod.traversal.com/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="OpenCode">
    Add to your `opencode.json` config:

    ```json theme={null}
    {
      "$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.
  </Accordion>

  <Accordion title="Other clients">
    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.
  </Accordion>
</AccordionGroup>

## Available tools

| Tool                  | Description                                                                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `investigate`         | Run a fast first-pass investigation (typically 30s–2min). The agent passes the incident, what it can access, and how focused to be.             |
| `follow_up`           | Continue an investigation using its `session_id` — drill into findings, verify a hypothesis, or feed back evidence your agent gathered locally. |
| `get_investigation`   | Get the status and report for an investigation, with a `ui_url` link to the web app.                                                            |
| `list_investigations` | List recent investigations for your organization.                                                                                               |
| `product_feedback`    | Send feedback about the MCP experience to the Traversal team.                                                                                   |

<Tip>
  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.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="Why is an MCP investigation faster than the web app?">
    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.
  </Accordion>

  <Accordion title="Does Traversal run commands on my systems?">
    No. Traversal is [always read-only](/architecture/intro) 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.
  </Accordion>

  <Accordion title="Authentication failed (401)">
    Verify your API key is correct and hasn't been revoked. If you recently regenerated it, update your client configuration.
  </Accordion>

  <Accordion title="Investigation is slow or times out">
    Broad investigations can take up to 2 minutes. Try a surgical investigation first and use `follow_up` to expand scope.
  </Accordion>

  <Accordion title="Viewing results in the web app">
    Call `get_investigation` — the response includes a `ui_url` link to the full investigation in the Traversal web app.
  </Accordion>
</AccordionGroup>