# MCP Server

> Built-in Model Context Protocol server that lets AI assistants query spans, traces, metrics, alerts, and dashboards in Uptrace using natural language.

Uptrace ships with a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. It exposes your observability data as MCP tools and resources so AI assistants — Claude, Cursor, Continue, and others — can query telemetry, inspect alerts, and manage dashboards directly from your Uptrace project.

## Quick start

**Step 1.** Get your project ID from **Project Settings** or from the URL of any project page.

**Step 2.** Create a user API token at **User menu → Auth tokens**.

**Step 3.** Add the Uptrace MCP server to your AI assistant:

```sh
# Claude Code
claude mcp add --transport http uptrace https://<your-uptrace-host>/mcp/<project_id> \
  --header "Authorization: Bearer <your-user-token>"
```

Or add it to your `mcp.json`:

```json
{
  "mcpServers": {
    "uptrace": {
      "url": "https://<your-uptrace-host>/mcp/<project_id>",
      "headers": {
        "Authorization": "Bearer <your-user-token>"
      }
    }
  }
}
```

The MCP project page in Uptrace displays ready-to-paste `claude mcp add` and `codex mcp add` commands with your project ID and token pre-filled.

## Authentication

Each MCP request requires a **user API token** in the `Authorization` header:

```text
Authorization: Bearer <your-user-token>
```

A few things to know:

- **User-scoped, not project-scoped.** The token grants the same permissions the user has across all their projects. The `<project_id>` in the URL selects which project the tools operate on — the user must have access to it.
- **What it grants.** Read access to telemetry (spans, traces, metrics, alerts, monitors) and the ability to create, update, and delete dashboards. Treat it like a password.
- **SSO limitation.** User tokens do not work with SSO because SSO requires browser redirects. If your organization uses SSO, create a separate user account with static credentials and grant it access to the relevant projects.

## Tools

### Spans and traces

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list_spans
      </code>
    </td>
    
    <td>
      Return individual span records matching a UQL query. Best for inspecting details.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_span_groups
      </code>
    </td>
    
    <td>
      Aggregate spans into groups with metrics (count, error rate, percentiles).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_traces
      </code>
    </td>
    
    <td>
      Find individual traces using correlated sub-queries across multiple span types.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_trace_groups
      </code>
    </td>
    
    <td>
      Aggregate traces into groups using correlated multi-span sub-queries.
    </td>
  </tr>
</tbody>
</table>

All four tools accept Uptrace's full search syntax (word/phrase/AND/OR/exclude, regex, scoped attribute search) and UQL filters such as `where service_name = 'api'`, system filters (`httpserver:all`, `db:postgresql`, `log:error`), and duration filters in milliseconds.

### Alerts and monitors

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list_alerts
      </code>
    </td>
    
    <td>
      List alerts with filtering by status, priority, type, activity, or monitor.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get_alert
      </code>
    </td>
    
    <td>
      Get a single alert by ID with full event history and assignees.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_monitors
      </code>
    </td>
    
    <td>
      List monitor rules with type, state, query, channels, and active alerts.
    </td>
  </tr>
</tbody>
</table>

### Metrics

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        explore_metrics
      </code>
    </td>
    
    <td>
      Discover metrics: name, instrument, unit, description, attributes, library.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_metric_attributes
      </code>
    </td>
    
    <td>
      List attribute keys available for metrics, with kind, unit, and counts.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_metric_attribute_values
      </code>
    </td>
    
    <td>
      List distinct values for a specific metric attribute key.
    </td>
  </tr>
</tbody>
</table>

### Dashboards

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list_dashboards
      </code>
    </td>
    
    <td>
      List all dashboards in the current project.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_dashboard_tags
      </code>
    </td>
    
    <td>
      List dashboard tags used in the project.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get_dashboard_yaml
      </code>
    </td>
    
    <td>
      Export an existing dashboard as YAML.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        create_dashboard_from_template
      </code>
    </td>
    
    <td>
      Create a new dashboard from a YAML definition.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update_dashboard_from_template
      </code>
    </td>
    
    <td>
      Replace an existing dashboard's definition with new YAML.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete_dashboard
      </code>
    </td>
    
    <td>
      Permanently delete a dashboard by ID.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_dashboard_templates
      </code>
    </td>
    
    <td>
      List built-in dashboard templates.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get_dashboard_template
      </code>
    </td>
    
    <td>
      Get a built-in dashboard template by ID.
    </td>
  </tr>
</tbody>
</table>

Dashboard tools use the same YAML format as the [dashboard import/export feature](/features/dashboards/yaml).

## Resources

The MCP server also exposes resources that AI assistants can read directly:

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      URI
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        create_dashboard
      </code>
    </td>
    
    <td>
      <code>
        uptrace://skills/create-dashboard
      </code>
    </td>
    
    <td>
      Skill guide for the dashboard creation workflow.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dashboard_template_schema
      </code>
    </td>
    
    <td>
      <code>
        uptrace://dashboard-templates/schema
      </code>
    </td>
    
    <td>
      JSON Schema for validating dashboard YAML.
    </td>
  </tr>
</tbody>
</table>

## Related

- [Dashboard YAML Templates](/features/dashboards/yaml) — YAML schema used by dashboard tools
- [Observability as Code](/features/observability-as-code) — manage monitors, channels, and dashboards as code
- [Alerting](/features/alerting) — monitor types and notification channels