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 incidents, and manage monitors and dashboards directly from your Uptrace project.

Quick start

Step 1. Open Project Settings → MCP and select your AI assistant. The page shows the project's endpoint and a command for that client.

Step 2. When browser sign-in is available, copy the command without a token. For Claude Code:

claude mcp add --transport http uptrace https://<your-uptrace-api-host>/mcp/<project_id>

Open the sign-in URL shown by your client, sign in to Uptrace, and approve access to the project. Your organization can use SSO during this browser flow.

Step 3. If your client cannot open a browser, select Use a token instead on the MCP page. Choose or create a token, then copy the command it shows. For Claude Code:

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

You can also configure a token-based client in mcp.json:

json

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

Use the API URL from your Uptrace deployment for the MCP endpoint. It can differ from the web UI URL.

Authentication

The MCP server accepts an OAuth access token from browser sign-in or an API token in the Authorization: Bearer header.

Browser sign-in. The client opens Uptrace's login and consent pages. OAuth grants expire, apply to one project, and carry read or write scopes. You can revoke a grant from your account settings.
API tokens. The token alternative is useful for clients without browser sign-in. A user token follows that user's project permissions and does not expire automatically. Treat it like a password.
Project access. The <project_id> in the URL selects the project. Your account must have access to it. Write tools also require write permission.

Self-hosted operators can configure these methods with mcp and oauth settings.

Tools

Spans, logs, and events

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.
`get_span`	Get one span with its event and log children and a formatted SQL query.
`get_trace`	Get one trace as a span tree, with its log and event records.
`list_logs`	Return individual log records matching a query.
`list_log_groups`	Aggregate log records into groups, for example to find which service writes the most errors.
`list_events`	Return individual event records, such as messages and Sentry breadcrumbs.
`list_event_groups`	Aggregate event records into groups.

The list 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 monitors with type, state, query, channels, and active alerts.
`get_monitor_yaml`	Export one monitor as a YAML document.
`preview_monitor_series`	Run a draft monitor query and return the series it selects, with sparklines. Creates nothing.
`create_threshold_monitor`	Create a monitor that fires when a metric leaves a fixed range.
`create_anomaly_monitor`	Create a monitor that fires on a departure from a model fitted on the metric's history.
`create_outlier_monitor`	Create a monitor that fires when one series of a grouped query departs from its peers.
`create_forecast_monitor`	Create a monitor that fires when a projected crossing falls within the forecast horizon.
`create_error_monitor`	Create a monitor that fires on the log records a query selects.
`create_slo_monitor`	Create an SLO monitor from a good-events query and a total-events query.
`update_threshold_monitor`, `update_anomaly_monitor`, `update_outlier_monitor`, `update_forecast_monitor`	Replace a metric monitor. A metric monitor can change to another of these four types.
`update_error_monitor`	Replace an error monitor.
`update_slo_monitor`	Replace an SLO monitor.
`delete_monitor`	Permanently delete a monitor and its alerts.

Incidents

Tool	Description
`list_incidents`	List incidents, filtered by status, priority, assignee, or text.
`count_incidents`	Count incidents per status and priority for the same filters.
`get_incident`	Get one incident, optionally with a preview of its alerts, events, and recommendations.
`list_incident_alerts`	List the alerts attached to an incident.
`list_incident_events`	List an incident's timeline: status and priority changes, alerts, notes, and assignments.
`get_incident_analysis`	Get the generated analysis of an incident and the evidence behind it.
`list_incident_recommendations`	List the recommended actions for an incident and their decision state.
`list_project_recommendations`	List the recommendations awaiting a decision across the project.
`decide_incident_recommendation`	Accept or reject a pending recommendation.
`create_incident_from_alerts`	Create an incident from one or more existing alerts.
`attach_alert_to_incident`	Attach alerts to an existing incident.
`remove_alert_from_incident`	Remove alerts from an incident.
`merge_incidents`	Merge one incident into another.
`resolve_incidents`, `reopen_incidents`, `close_incidents`	Change the status of one or more incidents.
`archive_incidents`, `unarchive_incidents`	File incidents away, until a time or permanently, and take them back.
`update_incident_details`	Update an incident's title and summary.
`update_incident_priority`	Override an incident's priority, or restore the derived one.
`assign_incident`	Set the owners of an incident.
`add_incident_note`, `update_incident_note`, `delete_incident_note`	Manage notes on the incident timeline.

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`	Create a new dashboard from a YAML definition.
`update_dashboard`	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.
`create_monitor`	`uptrace://skills/create-monitor`	Skill guide for creating monitors: the monitor types, their settings, query preview, and which create tool to use.

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