MCP Server

Uptrace ships with a built-in Model Context Protocol (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:

# 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

Tool	Description
`list_spans`	Return individual span records matching a UQL query. Best for inspecting details.
`list_span_groups`	Aggregate spans into groups with metrics (count, error rate, percentiles).
`list_traces`	Find individual traces using correlated sub-queries across multiple span types.
`list_trace_groups`	Aggregate traces into groups using correlated multi-span sub-queries.

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

Tool	Description
`list_alerts`	List alerts with filtering by status, priority, type, activity, or monitor.
`get_alert`	Get a single alert by ID with full event history and assignees.
`list_monitors`	List monitor rules with type, state, query, channels, and active alerts.

Metrics

Tool	Description
`explore_metrics`	Discover metrics: name, instrument, unit, description, attributes, library.
`list_metric_attributes`	List attribute keys available for metrics, with kind, unit, and counts.
`list_metric_attribute_values`	List distinct values for a specific metric attribute key.

Dashboards

Tool	Description
`list_dashboards`	List all dashboards in the current project.
`list_dashboard_tags`	List dashboard tags used in the project.
`get_dashboard_yaml`	Export an existing dashboard as YAML.
`create_dashboard_from_template`	Create a new dashboard from a YAML definition.
`update_dashboard_from_template`	Replace an existing dashboard's definition with new YAML.
`delete_dashboard`	Permanently delete a dashboard by ID.
`list_dashboard_templates`	List built-in dashboard templates.
`get_dashboard_template`	Get a built-in dashboard template by ID.

Dashboard tools use the same YAML format as the dashboard import/export feature.

Resources

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

Resource	URI	Description
`create_dashboard`	`uptrace://skills/create-dashboard`	Skill guide for the dashboard creation workflow.
`dashboard_template_schema`	`uptrace://dashboard-templates/schema`	JSON Schema for validating dashboard YAML.

Dashboard YAML Templates — YAML schema used by dashboard tools
Observability as Code — manage monitors, channels, and dashboards as code
Alerting — monitor types and notification channels