Documentation

Getting Started

Monocle MCP

Let Claude Code, Cursor, and other AI assistants query your production telemetry

Monocle supports the Model Context Protocol (MCP), enabling AI assistants like Claude Code, Cursor, and others to interact directly with your observability data. Let your AI tools help you debug issues, analyze traces, and explore your application's telemetry.

This server reads the data stored in Monocle cloud. For telemetry from your local development environment, use the Studio MCP server that ships with Monocle Studio.

Connect your assistant

  1. Add the server
    Terminal
    npx add-mcp https://api.monocle.sh/mcp

    This works with any MCP client that supports OAuth: Claude Code, Claude Desktop, Cursor, and others.

  2. Approve access

    Monocle uses OAuth 2.1. Your client opens your browser, you approve access, and the client handles the rest. Your assistant isn't tied to one application: it moves between your organizations, applications, and environments with list_apps and list_environments.

  3. Ask a question
    • Which new or regressed Issues should I look at first?
    • Fix the Issue at this URL, then resolve it with a note: <pasted Issue URL>
    • What's the P95 latency for POST /api/orders?
    • Why did the API health monitor go down last night?
    • Add p95 latency and error rate alerts on our 10 busiest endpoints, sent to #alerts
    • Create a dashboard with charts for request latency and error rate

Tools

Tools are grouped by what they help you do. Tools marked Write create or change data: they need the mcp:write or mcp:full scope and manager access to the project. Without one of these scopes, your client doesn't see them.

Workspace and setup

whoami

Get the current user and every organization, application, and environment you can access

list_apps
List the applications of your organizations
list_environments
List the environments of an application
setup_serviceWrite

Create a service, or reuse the one with the same name, and get its DSN with install steps, so your agent can instrument a repository

Issues and exceptions

Monocle groups exceptions into automatic Issues, which carry a status, a priority, assignees, comments, and a history. The issue tools accept an Issue ID, a Monocle Issue URL pasted from your browser, or the Issue's canonical fingerprint.

list_issues

List Issues to triage, filtered by status, triage reason (new, regressed, high priority, unassigned), priority, assignee (me), service, or search

get_issue

Get an Issue with its counts, services, stack location, and linked Linear or GitHub ticket. Optionally add the latest occurrence, comments, or activity

get_issue_activity

Get the history of an Issue: status, priority, and assignee changes, regressions, merges, and comments, with who did what and when

update_issueWrite

Resolve, archive, or reopen an Issue, change its priority or assignees, and explain why in a comment

add_issue_commentWrite

Post a comment on an Issue

link_issueWrite

Create a Linear or GitHub ticket for an Issue, or attach an existing one from its URL

list_exceptions

List raw exception groups with occurrence counts and affected users

get_exception

Get an exception group with its stack trace, timeline, and affected routes

list_occurrences

List the occurrences of an exception group, with their trace ID, timestamp, user, and route

A typical session starts with list_issues, opens one Issue with get_issue, follows its canonicalFingerprint into get_exception or list_occurrences, and ends with update_issue once the fix ships. Changes made through MCP appear in the Issue activity under your name and send no email.

link_issue uses the Linear or GitHub integration of your organization. A new ticket goes to the team you pass, or to the repository or team configured for the application. If the Issue already has a ticket for that provider, the tool returns it instead of creating another one.

Traces and logs

list_traces

List distributed traces, filtered by time range, status, service, or search

get_trace
Get every span of a trace
list_logs
List logs, filtered by severity, service, time range, or trace ID
search_logs
Search the text of log messages

Performance

list_endpoints

List HTTP endpoint patterns with their request count, average and p95 duration, and error rate

get_endpoint_stats

Get the latency percentiles, error rates, throughput, and time series of one endpoint

list_db_queries

List database query patterns with their execution count, duration, errors, and slow queries

get_db_query_detail

Get the recent executions of a query pattern, with their trace IDs and HTTP routes

list_jobs

List background jobs with their published and processed counts, error rate, and processing time

get_job_detail

Get the recent executions of a job, with their duration, queue time, status, and errors

list_cache_stats

List cache keys with their hit and miss rates, operation counts, and latency

get_cache_key_detail

Get the hit and miss time series, duration, and operations of a cache key

list_external_calls

List third-party API domains with their request count, latency, error rate, and status codes

get_external_call_detail

Get the URL patterns, recent requests, and performance of one domain

Metrics

list_instances

List the service instances (pods or replicas) reporting metrics

list_metrics

Discover the available metrics (gauges, sums, histograms, summaries) with their types and units

get_metric

Query a metric over time with an aggregation (avg, sum, min, max, p50 to p99), filters, and grouping

get_metric_attributes

Discover the attribute keys and values of a metric, to filter or group by in get_metric

Deployments

list_deployments

List the deployments of the environment, filtered by service, source, or version

get_deployment

Get a deployment with its timeline, the previous deployment, and the versions observed around it

Uptime and status incidents

Monocle separates the outages it detects from the status incidents your team declares. An outage is a period when a monitor failed. A status incident is what your status page shows.

list_monitors

List the uptime monitors of the environment, with their status, uptime, and median latency over the last 24 hours

get_monitor

Get a monitor with its statistics over 24 hours, 7 days, or 30 days, its 10 latest outages, and its 10 latest isolated failed checks

get_check

Inspect one check: its HTTP response, its health report, the checks around it, its outage, and its trace ID

list_outages

List detected outages, ongoing or recent, with the incidents they are linked to. Filter by monitor, by age (up to 90 days), or on outages not declared yet

get_outage
Get an outage, with its failed checks grouped by reason
list_status_incidents

List status incidents and scheduled maintenances, newest first. Resolved and cancelled ones are left out by default

get_status_incident

Get a status incident or maintenance with its updates, the affected monitors, and the linked outages

create_status_incidentWrite

Declare an incident, from detected outages or with the impact on each monitor, or schedule a maintenance window. Choose whether it is public

update_status_incidentWrite

Post a timeline update and change the status, resolve, cancel a maintenance that hasn't started, reschedule it, or edit the title, visibility, and affected monitors

A public incident or maintenance publishes its title and messages on your status page. Changing the status of an incident needs a message. A maintenance completes on its own at the end of its window.

Alerts

Create and manage endpoint alerts, for example to cover the busiest endpoints returned by list_endpoints.

list_alerts

List the alerts of the environment with their condition, destinations, status, and last value. Filter by endpoint

get_alert

Get an alert with the values it evaluated, its incidents over the time range, and its latest incident

list_notification_channels

List the Slack, Discord, and webhook channels of the organization, to send an alert to them. Webhook URLs are never returned

preview_alertWrite

Simulate a condition on recent data without saving it: when it would have fired, and a suggested threshold. Saves nothing, but needs the same access as the preview in the app

create_alertWrite

Create an alert on an endpoint: a latency percentile, an error rate, or a request rate compared to a threshold over a window

update_alertWrite

Change some fields of an alert. The fields you leave out keep their value

pause_alertWrite

Pause an alert. A firing alert resolves

resume_alertWrite

Resume a paused alert

An alert created through MCP starts paused, so it sends nothing until you review it and your assistant calls resume_alert, or you resume it from the Alerts page. Pass enabled: true to start it right away. Paused alerts don't count toward the limit of active alerts per organization. Notification channels are managed in your organization settings, not through MCP.

Custom dashboards

Build dashboards of metric widgets on a 12-column grid.

list_dashboards
List the custom dashboards with their widget counts
get_dashboard

Get a dashboard with its widgets: data sources, display, and layout

create_dashboardWrite

Create an empty dashboard

update_dashboardWrite

Change the name, description, or icon of a dashboard

delete_dashboardWrite

Delete a dashboard and all its widgets

add_widgetWrite

Add a chart, stat, table, sparkline, pie, or bar gauge widget

update_widgetWrite

Change the metric, aggregation, display, or layout of a widget

remove_widgetWrite

Remove a widget from a dashboard

Search documentation

Search pages and sections of the Monocle documentation