MCP Server

Uptrace ships with a built-in Model Context Protocol server. It exposes observability data and dashboard management as MCP tools and resources, so AI assistants (Claude, Cursor, Continue, etc.) can query telemetry, inspect alerts, and create dashboards directly from your Uptrace project.

Connecting an MCP client

The MCP server runs as part of the Uptrace API process and is mounted per project at:

text

https://<your-uptrace-host>/mcp/<project_id>

Replace <project_id> with the numeric ID of the Uptrace project you want the assistant to operate on. You can find it in Project Settings or in the URL of any project page.

Authentication

Each MCP request must carry an Uptrace user API token in the standard Authorization header:

text

Authorization: Bearer <your-user-token>

A few things to know about the token:

User-scoped, not project-scoped. MCP authenticates as a user, not as a project. The token grants the same permissions the user has across the projects they belong to. The <project_id> in the URL only selects which project the tools operate on — the user must have access to it.
Where to get it. In Uptrace, open the MCP page for the project (or go to User Menu → Auth tokens), create a new token, and copy the value. The MCP project page also displays ready-to-paste claude mcp add and codex mcp add commands that embed your token.
What it grants. The token inherits the user's permissions: read access to telemetry (spans, traces, metrics, alerts, monitors) and the ability to create, update, and delete dashboards via the dashboard tools. Treat it like a password and rotate it from User Menu → Auth tokens if it leaks.

Most MCP clients let you configure a custom HTTP header per server. A typical mcp.json-style entry looks like:

json

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

Or via the Claude Code CLI:

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

Once connected, the assistant will see the tools and resources listed below and can invoke them on your behalf.

Tools

The MCP server exposes the following tools, grouped by area.

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 (partial/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 mutating tools accept the same YAML format used by the dashboard import/export feature. See the dashboard YAML reference for the full schema.

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.

JavaScript Source MapsAutomatically unminify JavaScript stack traces using source maps. Upload source maps via API or let Uptrace fetch them from URLs.

Spans and LogsMaster the Uptrace span query language including identifiers, filters, grouping, and aggregates for traces, logs, and events.