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.
Authentication
Monocle uses OAuth 2.1 to authenticate MCP connections. Your MCP client handles the full authorization flow — you just approve access in your browser.
OAuth users are not tied to a single application. You can navigate between organizations, applications, and environments using the list_apps and list_environments tools.
Getting Started
npx add-mcp https://api.monocle.sh/mcpThis works with any MCP client that supports OAuth (Claude Code, Claude Desktop, Cursor, etc.).
Start Asking Questions
Once connected, you can ask your AI assistant questions about your application:
- "What exceptions occurred in the last hour?"
- "Show me the slowest API endpoints"
- "Find traces with errors from the checkout service"
- "What's the P95 latency for the /api/users endpoint?"
Available Tools
Your AI assistant has access to the following tools:
Navigation
| Tool | Description |
|---|---|
whoami | Get current authentication context (org, app, environment) |
list_apps | List applications in your organization |
list_environments | List available environments for your application |
Setup
| Tool | Description |
|---|---|
setup_service | 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 |
Traces
| Tool | Description |
|---|---|
list_traces | List distributed traces with filters (time range, status, service, search) |
get_trace | Get all spans for a specific trace by ID |
Logs
| Tool | Description |
|---|---|
list_logs | List application logs with filtering (severity, service, time range, trace ID) |
search_logs | Full-text search across log messages |
Exceptions
| Tool | Description |
|---|---|
list_exceptions | List exception groups with occurrence counts and affected users |
get_exception | Get detailed info about an exception group (stacktrace, timeline, affected routes) |
list_occurrences | List the occurrences of an exception group, with their trace ID, timestamp, user, and route |
archive_exception | Archive an exception group to hide it from the default list (duration: 1h, 1d, 1w, 30d, or forever) |
create_issue | Create an issue to track one or more exceptions with priority and assignees |
update_issue | Update an issue's status (open, resolved, ignored), priority, or assignees |
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.
| Tool | Description |
|---|---|
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 declared status incidents, newest first. Resolved and cancelled incidents are left out by default. |
get_status_incident | Get a status incident with its updates, the affected monitors, and the linked outages |
declare_status_incident | Declare a status incident from one or more outages, with a title, a message, and whether it is public |
post_status_incident_update | Post an update to a status incident and set its status: investigating, identified, monitoring, or resolved |
A public incident publishes its title and messages on your status page. post_status_incident_update doesn't manage scheduled maintenance.
Deployments
| Tool | Description |
|---|---|
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 |
Metrics
| Tool | Description |
|---|---|
list_instances | List service instances (pods/replicas) reporting metrics |
list_metrics | Discover all available metrics (gauges, sums, histograms, summaries) with their types and units |
get_metric | Query time-series data for any metric with aggregation (avg, sum, min, max, p50–p99), filtering, and grouping |
get_metric_attributes | Discover attribute keys and values for a metric to use as filters or groupBy in get_metric |
Endpoints
| Tool | Description |
|---|---|
list_endpoints | List HTTP endpoint patterns with request count, avg/p95 duration, and error rate. Supports sorting, search, and method filtering |
get_endpoint_stats | Get detailed stats for a specific endpoint: latency percentiles, error rates, throughput, and time-series data |
Database Queries
| Tool | Description |
|---|---|
list_db_queries | List database query patterns with execution count, avg/p95/max duration, error count, and slow query detection |
get_db_query_detail | Get details for a specific query pattern: recent executions with trace IDs and related HTTP routes |
Background Jobs
| Tool | Description |
|---|---|
list_jobs | List background job executions with published/processed counts, error rate, and avg/p95 processing time |
get_job_detail | Get details for a specific job: recent executions with duration, queue time, status, and error messages |
Cache
| Tool | Description |
|---|---|
list_cache_stats | List cache keys with hit/miss rates, operation counts, and avg/p95 latency |
get_cache_key_detail | Get detailed metrics for a specific cache key: hit/miss time series, duration, and operation breakdown |
External Calls
| Tool | Description |
|---|---|
list_external_calls | List third-party API domains with request count, avg/p95 latency, error rate, and status code breakdown |
get_external_call_detail | Get details for a specific domain: URL patterns, recent requests with trace IDs, and performance metrics |
Custom Dashboards
Build and manage custom dashboards with metric widgets directly from your AI assistant. Dashboards use a 12-column grid layout.
| Tool | Description |
|---|---|
list_dashboards | List all custom dashboards with widget counts |
get_dashboard | Get a dashboard with all its widgets (data sources, display config, layout) |
create_dashboard | Create a new empty dashboard |
update_dashboard | Update a dashboard's name, description, or icon |
delete_dashboard | Permanently delete a dashboard and all its widgets |
add_widget | Add a widget to a dashboard (chart, stat, table, sparkline, pie, or bar-gauge) |
update_widget | Update a widget's metric, aggregation, display, or layout |
remove_widget | Remove a widget from a dashboard |
Write access
Tools that create or change data 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. The write tools are:
setup_servicearchive_exception,create_issue, andupdate_issuedeclare_status_incidentandpost_status_incident_updatecreate_dashboard,update_dashboard,delete_dashboard,add_widget,update_widget, andremove_widget
Example Queries
- What exceptions occurred in the last hour?
- What's the P95 latency for POST /api/orders?
- Search logs for "payment failed"
- Which database queries are the slowest?
- Create an issue for the recurring TypeError in checkout
- Create a dashboard with charts for request latency and error rate
- Why did the API health monitor go down last night?
- Declare a public incident for the ongoing checkout outage and post an update once it's fixed