Skip to main content
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.

​
Getting Started

​
1. Generate an API Key

Navigate to your application’s Settings > API Keys and create a new API key. Keep it safe - you’ll need it to configure your MCP client.

​
2. Configure Your MCP Client

Add Monocle to your MCP client configuration. The setup varies by client:
Add to your OpenCode config file (opencode.json):
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "monocle": {
      "type": "remote",
      "url": "https://api.monocle.sh/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
3. 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:

​
Traces

ToolDescription
list_tracesList distributed traces with filters (time range, status, service, search)
get_traceGet all spans for a specific trace by ID

​
Logs

ToolDescription
list_logsList application logs with filtering (severity, service, time range, trace ID)
search_logsFull-text search across log messages

​
Exceptions

ToolDescription
list_exceptionsList exception groups with occurrence counts and affected users
get_exceptionGet detailed info about an exception group (stacktrace, timeline, affected routes)
analyze_exceptionAI-powered root cause analysis via Holmes

​
Metrics

ToolDescription
list_instancesList service instances (pods/replicas) reporting metrics
get_system_metricsGet CPU, memory, heap, and event loop metrics

​
Endpoints

ToolDescription
get_endpoint_statsGet latency percentiles (P50, P95, P99), error rates, and throughput for an endpoint
ToolDescription
whoamiGet current authentication context (org, app, environment)
list_environmentsList available environments for your application
list_appsList applications in your organization

​
Example Queries

Here are some examples of what you can ask your AI assistant: Debugging Errors
  • What exceptions happened in the last 24 hours? Show me the most frequent ones.
  • Get the full stacktrace for the TypeError that’s affecting checkout.
  • Analyze the NullPointerException and suggest a fix.
Performance Investigation
  • What’s the P95 latency for POST /api/orders today?
  • Find the slowest traces from the last hour.
  • Show me CPU and memory usage for all instances.
Log Analysis
  • Search for logs containing ‘payment failed’.
  • Show me error logs from the auth service in the last 30 minutes.
  • Get all logs for trace ID abc123.

​
Environments

By default, requests use the production environment. To query a different environment, set the x-environment header in your MCP client configuration.

​
Authentication

MCP authentication uses your Monocle API key. Each API key is scoped to a specific application and can access all environments within that application. You can authenticate using either:
  • Authorization: Bearer YOUR_API_KEY header
  • x-api-key: YOUR_API_KEY header