> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetusk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Drift MCP

> Connect coding agents to API traffic data for intelligent debugging

[Tusk Drift MCP](https://github.com/Use-Tusk/drift-mcp) is an MCP server that enables AI agents like Claude and Cursor to search, analyze, and debug your application's live traffic.

With Drift MCP, your AI agent can:

* **Search API traffic** - Find specific requests by endpoint, status code, duration, or payload contents
* **Analyze performance** - Calculate latency percentiles, error rates, and traffic patterns
* **Debug distributed traces** - View full request/response traces with PII redacted

<Info>
  New to Tusk Drift? Check out the [Drift overview](/api-tests/overview) to get
  started.
</Info>

## Setup

Choose between a hosted remote server (recommended) or running locally.

<Tabs>
  <Tab title="Remote Server (Recommended)">
    Connect directly to the hosted Tusk Drift MCP server. No local installation required.

    <AccordionGroup>
      <Accordion title="Cursor">
        Add to your Cursor MCP settings (`~/.cursor/mcp.json` or workspace `.cursor/mcp.json`):

        ```json theme={null}
        {
          "mcpServers": {
            "tusk-drift": {
              "url": "https://api.usetusk.ai/api/drift-mcp",
              "headers": {
                "x-api-key": "YOUR_TUSK_API_KEY"
              }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Claude Code">
        **Option A** — CLI command:

        ```bash theme={null}
        claude mcp add --transport http tusk-drift https://api.usetusk.ai/api/drift-mcp \
          --header "x-api-key: YOUR_TUSK_API_KEY"
        ```

        **Option B** — Add to `.mcp.json` in your project root:

        ```json theme={null}
        {
          "mcpServers": {
            "tusk-drift": {
              "type": "http",
              "url": "https://api.usetusk.ai/api/drift-mcp",
              "headers": {
                "x-api-key": "YOUR_TUSK_API_KEY"
              }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Claude Desktop">
        Add to your `claude_desktop_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "tusk-drift": {
              "command": "npx",
              "args": ["-y", "mcp-remote", "https://api.usetusk.ai/api/drift-mcp"],
              "env": {
                "MCP_HEADERS": "{\"x-api-key\": \"YOUR_TUSK_API_KEY\"}"
              }
            }
          }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Local Installation">
    Run the MCP server locally for offline access or custom configuration.

    Add the published package directly to your MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "tusk-drift": {
          "command": "npx",
          "args": ["-y", "@use-tusk/drift-mcp"],
          "env": {
            "TUSK_API_KEY": "YOUR_TUSK_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Configuration

| Variable                | Required | Description                                                                                            |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `TUSK_API_KEY`          | Yes      | Your Tusk API token                                                                                    |
| `TUSK_DRIFT_API_URL`    | No       | Backend base URL (defaults to `https://api.usetusk.ai`).                                               |
| `TUSK_DRIFT_SERVICE_ID` | No       | Default service ID. Auto-discovered from `.tusk/config.yaml` if not set                                |
| `TUSK_WORKSPACE_ROOTS`  | No       | Comma-separated workspace roots to search for `.tusk/config.yaml` files when auto-discovering services |

## Available Tools

The MCP server exposes six tools for different observability workflows:

<CardGroup cols={2}>
  <Card title="query_spans" icon="magnifying-glass">
    Search API traffic with flexible filters including endpoint, status code,
    duration, and request/response payloads.
  </Card>

  <Card title="get_schema" icon="diagram-project">
    Understand the structure of captured traffic for different instrumentation
    types (HTTP, database, gRPC).
  </Card>

  <Card title="list_distinct_values" icon="list">
    Discover what endpoints exist, which status codes are returned, and other
    field values in your traffic.
  </Card>

  <Card title="aggregate_spans" icon="chart-line">
    Calculate performance metrics: latency percentiles (p50, p95, p99), error
    rates, and request counts.
  </Card>

  <Card title="get_trace" icon="sitemap">
    View distributed traces as hierarchical trees for end-to-end debugging
    across services.
  </Card>

  <Card title="get_spans_by_ids" icon="database">
    Fetch specific spans by ID with full request/response payloads for detailed
    inspection.
  </Card>
</CardGroup>

## Usage Examples

Here are common workflows you can perform with AI agents using Drift MCP.

### Analyze endpoint performance

Ask your AI agent:

> "What are the slowest endpoints in my application? Show me p95 latency and error rates"

The agent will use `aggregate_spans` to calculate metrics:

```json theme={null}
{
  "groupBy": ["name"],
  "metrics": ["count", "p95Duration", "errorRate"],
  "orderBy": { "metric": "p95Duration", "direction": "DESC" }
}
```

### Debug a failing request

Ask your AI agent:

> "Show me the full trace for this failed request to /api/checkout"

The agent will:

1. Use `query_spans` to find the failing request
2. Extract the `traceId` from the result
3. Use `get_trace` to display the full request chain

### Find requests with specific payload data

Ask your AI agent:

> "Find all requests where the response included an error message containing 'payment failed'"

The agent will use the shared recursive `where` shape to search response payloads:

```json theme={null}
{
  "where": {
    "fields": {
      "outputValue.body.error": {
        "contains": "payment failed"
      }
    }
  }
}
```

## Multi-Service Support

If you have multiple services instrumented with Tusk Drift, the MCP server automatically discovers them from `.tusk/config.yaml` files in your workspace.

When querying, specify the service:

> "Show me the slowest requests in the payments-service"

The agent will include `observableServiceId` in the query to target the correct service.

<Tip>
  Looking for a simpler alternative? [Agent Skills](/agent-skills) give your AI
  agent the same Drift workflows without MCP server configuration — install once
  and they work across all supported agents.
</Tip>

## Support

Need help? Contact us at [support@usetusk.ai](mailto:support@usetusk.ai) or open an issue on [GitHub](https://github.com/use-tusk/drift-mcp).