monitor-mcp

MCP server for the Monitor observability platform. Gives Claude Code direct access to query events, analyze errors, trace requests, and diagnose issues across services.

Quick Start

npx monitor-mcp --setup

This prompts for your Monitor API URL and API key, writes the config to ~/.mcp.json, and you're ready to go. Restart Claude Code after setup.

Generate an API key from the Monitor web dashboard under Settings > API Keys.

Manual Setup

Add to ~/.mcp.json:

{
  "mcpServers": {
    "monitor": {
      "command": "npx",
      "args": ["-y", "monitor-mcp"],
      "env": {
        "MONITOR_API_URL": "https://api.monitor.appleby.cloud",
        "MONITOR_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

Discovery

Tool	Description
monitor_health	API health and queue stats (enqueued, dropped, pending)
monitor_list_services	List all services sending events
monitor_list_environments	List all environments (prod, staging, dev)
monitor_list_event_names	List event names, optionally filtered by service
monitor_list_levels	List log levels in use
monitor_list_users	List user IDs that have generated events

Event Search

Tool	Description
monitor_search_events	Search events with Django-style filters (field__operator=value)
monitor_trace	Get all events for a trace ID across services
monitor_request	Get all events for a request ID

Data Fields

Tool	Description
monitor_get_data_keys	List custom data field keys in events
monitor_get_data_values	List distinct values for a data field

Analytics

Tool	Description
monitor_count	Count events matching filters
monitor_analytics	Aggregation query with grouping (count, sum, avg, p99, etc.)
monitor_timeseries	Time-bucketed trend data (minute/hour/day/week/month)
monitor_topn	Top N values by field
monitor_compare	Period-over-period comparison with change percentage

Quick Diagnostics

Tool	Description
monitor_recent_errors	Most recent error and fatal events
monitor_error_breakdown	Error frequency grouped by name, service, or endpoint
monitor_error_trend	Error count over time (is it getting worse?)
monitor_service_overview	Composite health summary — total events, error count, error rate, top events, top errors

Example Prompts

• "What errors happened in the last hour?"
• "Show me the error trend for forta-api today"
• "Trace request abc-123 across services"
• "Compare error rates this week vs last week"
• "Give me an overview of the johnnies-api service"
• "What are the top 10 most common errors?"
• "Find all events where data.status_code >= 500"

Filter Syntax

Event search supports Django-style filter operators:

Operator	Example	Description
eq (default)	service=my-api	Exact match
neq	level__neq=info	Not equal
contains	name__contains=error	Substring match
startswith	name__startswith=http	Prefix match
gt, gte, lt, lte	data.status_code__gte=400	Numeric comparison
in	level__in=error,fatal	Match any value

Data fields use the data. prefix: data.endpoint__contains=/api, data.status_code__gte=500.

Environment Variables

Variable	Required	Description
MONITOR_API_URL	Yes	Monitor API base URL
MONITOR_API_KEY	Yes	API key for authentication (via X-Api-Key header)

License

MIT