datadog-mcp
Provides tools for searching logs, querying metrics, managing dashboards, analyzing APM traces, and controlling monitors in Datadog.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@datadog-mcp show me error logs from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.pyis a thin composition layer: it wires each domain'sregister_<domain>_tools(mcp)into oneFastMCPinstance 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 itsregister_<domain>_tools(mcp)function with the@mcp.tooldecorators + docstrings.auth.py- theDatadogAuth/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: inboundDatadogModel(tolerant,extra="ignore") vs. outboundToolResponse/PaginatedListResponse(strict,extra="forbid"), size-based truncation, and Datadog error classification (403 ā missing scope, 429 ā rate limit).utils/annotations.py- shared, honestToolAnnotationspresets (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
intervalfor 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, seefinalize_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 calldatadog://widget-templates- Ready-to-use widget JSON forcreate_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 |
| ā | ā | ā | All search/list/get/count/aggregate/validate tools |
| ā | ā | ā |
|
| ā | ā | ā |
|
| ā | ā | ā |
|
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_readWrite:
metrics_write,dashboards_write,monitors_write,monitors_downtime_write
1. Install dependencies
cd /path/to/datadog-mcp
uv sync --frozenuv 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 directlyTesting
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_KEYHandshake test (
tests/test_handshake.py): boots the server in-memory viafastmcp.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
Add Pydantic request/response models and the
_function(...)implementation to the relevanttools/<domain>.py(or a new domain module).Register the
@mcp.tool(annotations=...)-decorated wrapper inside that module'sregister_<domain>_tools(mcp), with a docstring following the convention in.cursor/rules/documentation-standards.mdc.Verify the required Datadog scope against
docs/SCOPE_VERIFICATION.md/scripts/verify_scopes.pybefore writing the tool - this app key is exclusive to this server and has a fixed, narrow scope set.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 promptTroubleshooting
Server not appearing in Cursor
Confirm the
--directorypath inmcp.jsonis absolute and correct.Confirm
DD_API_KEY/DD_APP_KEYresolve 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_SITEmatches your Datadog region; a mismatched site behaves like an auth failure.
Import errors after pulling changes
uv sync --frozenAPI documentation
License
MIT License - See LICENSE file for details.
Available Tools
30 toolsaggregate_logs_by_fieldARead-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_spansARead-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_logsARead-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_valuesARead-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_metricARead-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_detailsARead-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_downtimeARead-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_traceARead-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_detailsARead-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_detailsARead-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_metricsARead-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_dashboardsARead-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_monitorsARead-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_servicesARead-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_metricsARead-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_downtimesARead-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_metricsARead-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_tracesARead-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_logsARead-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_monitorsARead-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_monitorAIdempotent
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_monitorAIdempotent
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_monitorADestructiveIdempotent
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_downtimeADestructiveIdempotent
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_dashboardADestructiveIdempotent
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_monitorARead-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
Scored across 30 tools
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.
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.
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.
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
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Query your app's logs, metrics and incidents from your AI assistant.
Query your AI agent traces, root-cause verdicts and issues, and run investigations, from your agent.
1
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT
- AlicenseCqualityCmaintenanceEnables 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.10017 npmApache 2.0
- FlicenseBqualityDmaintenanceEnables AI assistants to interact with Datadog APIs for querying metrics, logs, events, monitors, and APM traces.164-
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Datadog APIs through natural language, supporting full CRUD operations on metrics, monitors, dashboards, logs, infrastructure, and more.4MIT