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.
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/mcp
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?”
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 |
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) |
analyze_exception | AI-powered root cause analysis via Holmes |
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 |
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 |
Dashboard tools that create or modify data (create_dashboard, update_dashboard, delete_dashboard, add_widget, update_widget, remove_widget) require the mcp:write scope.
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
