Skip to main content
Glama
datadog-mcp

datadog-mcp

by techskies11

Datadog MCP Server

A Model Context Protocol server that connects AI agents (Cursor, Claude, etc.) to Datadog. Search logs, query metrics, manage dashboards, analyze APM traces, and manage monitors/downtimes - all from your AI assistant, using the app key's real permissions.

Built with FastMCP and Pydantic. No deletes, no destructive dashboard/monitor removal, and every tool response is a validated Pydantic model with a consistent success/error shape.

Architecture

  • server.py is a thin composition layer: it wires each domain's register_<domain>_tools(mcp) into one FastMCP instance and defines resources/prompts. It does not contain tool implementations.

  • tools/*.py - one module per Datadog domain (logs, aggregations, metrics, apm, dashboards, monitors, downtimes). Each module owns its Pydantic models, its internal _function(...) implementation (auth injected explicitly, easy to unit test), and its register_<domain>_tools(mcp) function with the @mcp.tool decorators + docstrings.

  • auth.py - the DatadogAuth/get_auth_instance() singleton. Same env vars as before (DD_API_KEY, DD_APP_KEY, DD_SITE); no auth behavior changed in this revamp.

  • utils/response.py - shared Pydantic response infrastructure: inbound DatadogModel (tolerant, extra="ignore") vs. outbound ToolResponse/PaginatedListResponse (strict, extra="forbid"), size-based truncation, and Datadog error classification (403 → missing scope, 429 → rate limit).

  • utils/annotations.py - shared, honest ToolAnnotations presets (see the table below).

See ARCHITECTURE.md for the full request flow and docs/SCOPE_VERIFICATION.md for the scope research behind every tool.

Related MCP server: MCP Datadog Server

Tools

All tool names, response field names, and env vars are stable across this revamp - nothing below was renamed. 30 tools total.

šŸ” Logs

  • search_logs - Search and view log entries (paginated)

  • get_log_details - Full details of a single log by ID

  • count_logs - Fast count of logs matching a query (no content transfer)

  • count_unique_values - Count unique values of a field (e.g. distinct users)

  • aggregate_logs_by_field - Group/aggregate logs with statistics; optional interval for a timeseries breakdown

šŸ“Š Metrics

  • query_metrics - Query time series metrics with aggregations

  • list_available_metrics - Discover metric names matching a prefix

  • list_active_metrics - List metrics that reported data recently

  • describe_metric - Metadata (unit, type, description) + known tags for one metric, in a single call

  • send_custom_metric - Submit custom metrics (gauge, count, rate)

šŸ“ˆ Dashboards

  • list_all_dashboards - Browse all dashboards

  • get_dashboard_details - Complete dashboard config and widgets (large widget lists are truncated with a warning, see finalize_list_response)

  • create_new_dashboard - Create a dashboard with widgets/layout (common widget types are pre-flight validated - see datadog://widget-templates)

  • update_existing_dashboard - Modify an existing dashboard (overwrites given fields; no undo tool)

No delete tool exists for dashboards, by design.

šŸ”¬ APM / Traces

  • search_apm_traces - Search spans by service, operation, tags

  • get_full_trace - Full trace (all spans) by trace ID, via the dedicated per-trace endpoint

  • list_apm_services - Discover instrumented services

  • aggregate_spans - Latency/error statistics grouped by a facet, without pulling raw spans

🚨 Monitors

  • list_all_monitors - List monitors with filters (state, name, tags)

  • search_monitors - Full-text/faceted monitor search

  • get_monitor_details - Full monitor configuration

  • validate_monitor - Validate a monitor query/type before creating it

  • create_alert_monitor - Create a metric, log, APM, or composite monitor

  • update_alert_monitor - Modify an existing monitor's configuration

  • silence_monitor / unsilence_monitor - Mute/unmute a single monitor (one-off; see downtimes for scheduled/scoped muting)

No delete tool exists for monitors, by design.

šŸŒ™ Downtimes

  • list_downtimes - List scheduled/active downtimes

  • get_downtime - Full details of one downtime

  • schedule_downtime - Mute a scope of monitors (or one monitor) over a time window

  • update_downtime - Modify an existing downtime's schedule/scope

No cancel_downtime tool: it is a real, irreversible DELETE and is intentionally excluded pending explicit team sign-off (see utils/annotations.py).

Resources

  • datadog://status - Quick health snapshot (alerting monitor count/names); makes exactly one Datadog API call

  • datadog://widget-templates - Ready-to-use widget JSON for create_new_dashboard/update_existing_dashboard (timeseries, query_value, toplist, heatmap)

Prompts

  • investigate_errors(service?, env, lookback) - Guided error investigation across logs/APM/monitors

  • performance_analysis(service?, lookback) - Guided latency/performance investigation

  • triage_alerting_monitors(env?) - Prioritized triage of currently-alerting monitors

  • create_monitoring(target) - Guided monitor + dashboard creation

Tool safety annotations

Every tool declares an honest ToolAnnotations hint via one of four presets in utils/annotations.py:

Preset

readOnly

destructive

idempotent

Used by

READ_ONLY

āœ…

āŒ

āœ…

All search/list/get/count/aggregate/validate tools

WRITE_ADDITIVE

āŒ

āŒ

āŒ

create_new_dashboard, create_alert_monitor, schedule_downtime, send_custom_metric

WRITE_OVERWRITE

āŒ

āœ…

āœ…

update_existing_dashboard, update_alert_monitor, update_downtime (no undo tool exists, even though nothing is deleted)

STATE_TOGGLE

āŒ

āŒ

āœ…

silence_monitor / unsilence_monitor (reversible, matching inverse tool exists)

Installation

Prerequisites

  • Python 3.10+

  • uv (recommended)

  • A Datadog API key + Application key. The app key used by this server only needs (see docs/SCOPE_VERIFICATION.md for the full rationale):

    • Read: logs_read, metrics_read, dashboards_read, monitors_read, apm_read

    • Write: metrics_write, dashboards_write, monitors_write, monitors_downtime_write

1. Install dependencies

cd /path/to/datadog-mcp
uv sync --frozen

uv sync --frozen installs exactly what's pinned in uv.lock - the same versions CI tests against. Only drop --frozen (and run uv lock --upgrade first) when intentionally bumping dependencies.

2. Configure Cursor's mcp.json

Credentials belong in Cursor's mcp.json, not in this project. The .env.example file at the repo root is for local development only (e.g. running scripts/verify_scopes.py directly).

{
  "mcpServers": {
    "datadog": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/datadog-mcp",
        "run", "fastmcp", "run", "src/datadog_mcp/server.py"
      ],
      "env": {
        "DD_API_KEY": "${DD_API_KEY}",
        "DD_APP_KEY": "${DD_APP_KEY}",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}

Set DD_API_KEY/DD_APP_KEY in your shell profile and reference them with ${...} as above, or inline the raw values directly in mcp.json (less secure, simpler).

Datadog regions (DD_SITE): datadoghq.com (US1, default), us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com.

3. Restart Cursor

Restart Cursor IDE (or reload the MCP servers) to pick up the new server.

Pinning a version for rollback

Cursor's mcp.json can point --directory at a specific git worktree/tag/commit. If a change to this server ever breaks the team, pin the datadog-mcp checkout to the last known-good tag/commit and re-run uv sync --frozen there - no code changes required to roll back.

Development

Running locally

uv run fastmcp run --reload src/datadog_mcp/server.py   # dev server with auto-reload
uv run datadog-mcp                                       # or: run the installed script directly

Testing

uv run pytest                # unit + MCP handshake + tool-schema snapshot tests
uv run pytest -m live         # opt-in: real Datadog API calls, requires DD_API_KEY/DD_APP_KEY
  • Handshake test (tests/test_handshake.py): boots the server in-memory via fastmcp.Client, asserts every baseline tool/resource/prompt name is still present, and round-trips a mocked tool call end-to-end. This is the safety net against an import error taking down the server for the whole team.

  • Schema snapshot tests (tests/test_tool_schemas.py): every tool's input/output JSON schema is captured as a golden file; any shape change shows up in the PR diff instead of silently reaching the client. Regenerate intentionally-changed snapshots by running the test once with the update flag it defines, then reviewing the diff.

  • Live tests (pytest -m live): a handful of read-only smoke calls gated behind real credentials, skipped by default (including in CI).

Linting and type checking

uv run ruff check .
uv run ruff format .
uv run pyright src
uv run mypy src        # stricter, allowed to flag datadog-api-client's untyped calls (see inline `type: ignore[no-untyped-call]`)

CI (.github/workflows/ci.yml) runs ruff, ruff format --check, pyright, and pytest on every push/PR against the locked dependency set (uv sync --frozen). pre-commit runs the same ruff/pyright checks locally before commit.

Adding a new tool

  1. Add Pydantic request/response models and the _function(...) implementation to the relevant tools/<domain>.py (or a new domain module).

  2. Register the @mcp.tool(annotations=...)-decorated wrapper inside that module's register_<domain>_tools(mcp), with a docstring following the convention in .cursor/rules/documentation-standards.mdc.

  3. Verify the required Datadog scope against docs/SCOPE_VERIFICATION.md / scripts/verify_scopes.py before writing the tool - this app key is exclusive to this server and has a fixed, narrow scope set.

  4. Add a unit test under tests/tools/, then run the full suite - the handshake and schema snapshot tests will fail loudly if something regresses.

Usage examples

Search Datadog logs for errors in the api service in the last hour
→ search_logs(query="status:error service:api", from_time="now-1h", to_time="now")

Show me CPU usage for all hosts over the last 4 hours
→ query_metrics(query="avg:system.cpu.user{*}", from_time="now-4h", to_time="now")

Create a dashboard called "API Performance" with a timeseries widget for request latency
→ create_new_dashboard(...) using a template from datadog://widget-templates

Mute all monitors in staging this weekend
→ schedule_downtime(scope="env:staging", ...)

What's currently alerting?
→ the triage_alerting_monitors prompt

Troubleshooting

Server not appearing in Cursor

  • Confirm the --directory path in mcp.json is absolute and correct.

  • Confirm DD_API_KEY/DD_APP_KEY resolve to real values (check your shell profile if using ${...} interpolation).

  • Restart Cursor completely and check its MCP logs.

Authentication / 403 errors

  • Tool responses classify 403s with the likely missing scope - check it against docs/SCOPE_VERIFICATION.md.

  • Verify DD_SITE matches your Datadog region; a mismatched site behaves like an auth failure.

Import errors after pulling changes

uv sync --frozen

API documentation

License

MIT License - See LICENSE file for details.

Available Tools

30 tools
aggregate_logs_by_fieldA
Read-onlyIdempotent

Aggregate and group logs by a field with statistics (fast, no raw data transfer).

PERFECT for analytics, charts, and dashboards. Set interval to get a timeseries per group instead of a single scalar per group - this covers timeseries use cases without needing a separate tool.

Use this when:

  • "Group errors by service"

  • "Top 10 services by request count"

  • "Average duration per endpoint, per hour" (set interval="1h")

Inputs: query (required), to_time (required), group_by (required), from_time (required), +5 more. Returns: object

aggregate_spansA
Read-onlyIdempotent

Aggregate spans by a field for latency/error statistics (no raw span data transfer).

PERFECT for "what's slow" or "what's erroring" questions without paying the cost of fetching and reading raw spans with search_apm_traces.

Use this when:

  • "p95 latency by service"

  • "Error count by endpoint"

  • "Average duration per operation"

Inputs: query (required), to_time (required), group_by (required), from_time (required), +3 more. Returns: object

count_logsA
Read-onlyIdempotent

Count logs matching a query WITHOUT fetching all data (fast & lightweight).

PREFERRED for counting events - much faster than search_logs, which should never be used just to count results.

Use this when:

  • "How many errors happened?"

  • "Count logs for a service"

  • Need a number, not log content

Inputs: query (required), to_time (required), from_time (required), indexes. Returns: object

count_unique_valuesA
Read-onlyIdempotent

Count UNIQUE values of a field (distinct count / cardinality).

PERFECT for counting unique sessions, users, IPs, etc. Much more efficient than fetching all logs with search_logs and counting distinct values client-side.

Use this when:

  • "How many unique users/sessions?"

  • "Count distinct values"

  • "How many different X?"

Inputs: field (required), query (required), to_time (required), from_time (required), +1 more. Returns: object

create_alert_monitorA

Create a new monitor to alert on metrics, logs, or APM data.

Use this when: user wants to get notified about issues, set up alerting, or monitor SLAs. Consider validate_monitor first to check the query syntax before creating.

Query examples:

  • Metric: "avg(last_5m):avg:system.cpu.user{*} > 80"

  • Log: 'logs("status:error").index("*").rollup("count").last("5m") > 100'

  • APM: "avg(last_10m):trace.web.request{service:api}.errors.rate > 5"

Inputs: name (required), query (required), message (required), monitor_type (required), +3 more. Returns: object

create_new_dashboardA

Create a new dashboard with custom widgets and layout.

Use this when: user wants to visualize metrics, create a monitoring view, or track KPIs. See the datadog://widget-templates resource for ready-to-use widget definitions for the most common widget types (timeseries, query_value, toplist).

Layout types:

  • "ordered": Timeline view (widgets stacked vertically)

  • "free": Free-form placement (drag anywhere)

Inputs: title (required), widgets (required), layout_type (required), tags, +3 more. Returns: object

describe_metricA
Read-onlyIdempotent

Get metadata (description, unit, type) and known tags for a metric.

Use this when: you need to understand what a metric means or what tags you can group/filter by before writing a query_metrics or monitor query. Consolidates metric metadata and tag discovery into a single call.

Inputs: metric_name (required). Returns: object

get_dashboard_detailsA
Read-onlyIdempotent

Get complete dashboard configuration and widgets.

Use this when: need to see what's in a dashboard or copy its configuration. Large dashboards may have their widget list truncated (see the truncated/ warning/total_available fields) to stay within the response size budget.

Inputs: dashboard_id (required). Returns: object

get_downtimeA
Read-onlyIdempotent

Get complete details of a specific downtime.

Use this when: need to see a downtime's exact scope, schedule, or status.

Inputs: downtime_id (required). Returns: object

get_full_traceA
Read-onlyIdempotent

Get complete trace with all spans and timing information.

Use this when: need to see full request flow across services (after finding a trace ID).

Inputs: trace_id (required). Returns: object

get_log_detailsA
Read-onlyIdempotent

Get complete details of a specific log entry.

Use this when: need full information about a particular log (after searching).

Inputs: log_id (required). Returns: object

get_monitor_detailsA
Read-onlyIdempotent

Get complete monitor configuration and current status.

Use this when: need to see monitor details, thresholds, or notification settings.

Inputs: monitor_id (required). Returns: object

list_active_metricsA
Read-onlyIdempotent

List metrics that have reported data since a given time.

Use this when: you want to know what's actually emitting data recently, as opposed to list_available_metrics which lists every metric name Datadog knows about (including ones that stopped reporting long ago).

Inputs: host, since, tag_filter. Returns: object

list_all_dashboardsA
Read-onlyIdempotent

Browse all Datadog dashboards.

Use this when: want to see what dashboards exist or find a specific dashboard.

Inputs: limit, filter_query. Returns: object

list_all_monitorsA
Read-onlyIdempotent

Browse all monitors and their current alert states.

Use this when: want to see what's being monitored or check alert status. For a faceted/full-text search instead of exact filters, use search_monitors.

Inputs: name, tags, limit, group_states, +2 more. Returns: object

list_apm_servicesA
Read-onlyIdempotent

List services sending APM data in the last hour.

Use this when: want to see what services are instrumented or find service names.

Inputs: env, limit. Returns: object

list_available_metricsA
Read-onlyIdempotent

List all metrics available in Datadog.

Use this when: don't know the exact metric name, or want to discover what's available. For metric metadata (description, unit, type) and tags on a specific metric, use describe_metric instead.

Inputs: limit, filter. Returns: object

list_downtimesA
Read-onlyIdempotent

Browse scheduled/active downtimes (scoped monitor mutes).

Use this when: want to see what's currently muted org-wide, or audit upcoming maintenance windows.

Inputs: limit, current_only. Returns: object

query_metricsA
Read-onlyIdempotent

Query and visualize time series metrics.

Use this when: need to check system performance, resource usage, or custom metrics.

Common queries:

  • CPU: "avg:system.cpu.user{*}"

  • Memory: "avg:system.mem.used{*}"

  • By host: "avg:system.load.1{host:web-01}"

  • By tag: "sum:requests.count{env:prod}"

Inputs: query (required), to_time (required), from_time (required). Returns: object

schedule_downtimeA

Schedule a downtime to mute a scope of monitors (or one monitor) over a time window.

Use this when: silencing many monitors at once by scope/tag (e.g. "mute all alerts for env:staging this weekend"), or muting on a schedule with a known end time. For muting exactly one already-known monitor with no scheduling needs, silence_monitor is simpler. At most one of monitor_id/monitor_tags should be set; if neither is set, the downtime applies to all monitors matching scope.

Inputs: scope (required), message (required), end, start, +4 more. Returns: object

search_apm_tracesA
Read-onlyIdempotent

Search distributed traces and spans for performance analysis (paginated).

Use this when: debugging slow requests, finding errors in services, or analyzing latency. For statistics (latency percentiles, error rates) without fetching raw spans, use aggregate_spans instead - it is much lighter for dashboards/analytics.

Common queries:

  • Find errors: "service:api @error.message:*"

  • By status: "service:checkout @http.status_code:500"

  • Custom tags: "@airline_name:aeromexico @session_id:*"

Inputs: query (required), to_time (required), from_time (required), sort, +2 more. Returns: object

search_logsA
Read-onlyIdempotent

Search and VIEW log entries. Returns paginated results.

IMPORTANT: Use this ONLY when you need to VIEW log content for debugging. For COUNTING logs or unique values, use count_logs or count_unique_values instead - they are much faster and lighter since they never fetch raw log content.

Use this when:

  • Need to view actual log messages and details

  • Debugging specific issues

  • Investigating error details

DO NOT use for:

  • Counting logs (use count_logs)

  • Counting unique sessions/users (use count_unique_values)

  • Statistical analysis (use aggregate_logs_by_field)

Inputs: query (required), to_time (required), from_time (required), sort, +3 more. Returns: object

search_monitorsA
Read-onlyIdempotent

Full-text/faceted search across monitors (e.g. by tag, status, or text in the query/name).

Use this when: list_all_monitors's exact-match filters aren't enough - e.g. searching monitor names/queries by substring across facets at once.

Inputs: query, per_page. Returns: object

send_custom_metricA

Send custom metric data points to Datadog.

Use this when: need to track custom application metrics or business KPIs.

Metric types:

  • gauge: Point-in-time value (temperature, queue size)

  • count: Count of events in interval

  • rate: Events per second

Inputs: points (required), metric_name (required), host, tags, +2 more. Returns: object

silence_monitorA
Idempotent

Temporarily mute/silence monitor notifications.

Use this when: performing maintenance, testing, or a known issue doesn't need alerts right now, for a single monitor. For muting many monitors on a schedule by scope (e.g. "all monitors in this env, this weekend"), use schedule_downtime instead - it is Datadog's purpose-built tool for scheduled, scoped silencing.

Inputs: monitor_id (required), scope, end_timestamp. Returns: object

unsilence_monitorA
Idempotent

Resume notifications from a muted monitor.

Use this when: maintenance is complete or ready to receive alerts again.

Inputs: monitor_id (required), scope. Returns: object

update_alert_monitorA
DestructiveIdempotent

Modify an existing monitor's configuration. Overwrites given fields; rest is unchanged.

Use this when: need to adjust thresholds, change notifications, or update alert logic. There is no undo tool - the previous configuration is not recoverable once overwritten.

Inputs: monitor_id (required), name, tags, query, +3 more. Returns: object

update_downtimeA
DestructiveIdempotent

Modify an existing downtime's scope, schedule, or message.

Use this when: need to extend/shorten a downtime's window, change its scope, or end it early (set end to "now"). There is no undo tool - the previous downtime configuration is not recoverable once overwritten.

Inputs: downtime_id (required), end, scope, start, +3 more. Returns: object

update_existing_dashboardA
DestructiveIdempotent

Modify an existing dashboard. Overwrites the given fields; anything omitted is unchanged.

Use this when: need to add widgets, change layout, or update dashboard config. There is no undo tool for dashboard updates - the previous widget/config state is not recoverable through this server once overwritten.

Inputs: dashboard_id (required), tags, title, widgets, +4 more. Returns: object

validate_monitorA
Read-onlyIdempotent

Validate a monitor query's syntax without creating anything.

Use this when: want to check a monitor definition is well-formed before calling create_alert_monitor, especially for hand-built queries. This never creates, modifies, or persists a monitor - it is a pure syntax/semantics check.

Note: validating a "log alert" monitor may additionally require the app key to have log data read access without further scoping; if that's missing you will see a permission error here specifically for log-type queries even though other monitor types validate fine.

Inputs: query (required), monitor_type (required), message. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 30 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear boundaries between overlapping domains like logs, metrics, and APM. Tools such as search_logs, count_logs, and aggregate_logs_by_field are explicitly differentiated to prevent misuse, and descriptions cross-reference each other to guide correct selection.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using lowercase with underscores, such as get_*, list_*, search_*, count_*, create_*, update_*, and silence_*. No mixed conventions or camelCase appear, making the naming predictable and easy to navigate.

    Tool Count2/5

    With 30 tools, the server exceeds the 25-tool threshold for 'too many' and is well above the typical 3-15 tool range. While each tool serves a distinct purpose across multiple Datadog domains, the sheer number adds cognitive load for an agent and may require extra effort to choose correctly.

    Completeness3/5

    The toolset covers core workflows for logs, metrics, APM, dashboards, monitors, and downtimes, including create, read, and update operations. However, there are no delete operations for any resource (e.g., monitors, dashboards, downtimes), which is a notable gap in lifecycle management. Some areas, like APM services, only provide list functionality without deeper detail.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with DataDog's observability platform through a standardized interface. Supports monitoring infrastructure, managing events, analyzing logs and metrics, and automating operations like alerts and downtimes.
      1
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables interaction with Datadog APIs through automatically generated tools from Postman collections. Supports monitoring operations, log management, metrics submission, and other Datadog functionality through natural language.
      100
      17 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Datadog APIs through natural language, supporting full CRUD operations on metrics, monitors, dashboards, logs, infrastructure, and more.
      4
      MIT