Monocle MCP Server

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

This 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:

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

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Other

Authentication

Getting Started

Start Asking Questions

Available Tools

Navigation

Traces

Logs

Exceptions

Metrics

Endpoints

Database Queries

Background Jobs

Cache

External Calls

Custom Dashboards

Example Queries

​Authentication

​Getting Started

​Start Asking Questions

​Available Tools

​Navigation

​Traces

​Logs

​Exceptions

​Metrics

​Endpoints

​Database Queries

​Background Jobs

​Cache

​External Calls

​Custom Dashboards

​Example Queries

Authentication

Getting Started

Start Asking Questions

Available Tools

Navigation

Traces

Logs

Exceptions

Metrics

Endpoints

Database Queries

Background Jobs

Cache

External Calls

Custom Dashboards

Example Queries