·

What Is Datadog MCP

Learn what Datadog MCP is and how it lets your AI agent query metrics, logs, and monitors.

Datadog's Model Context Protocol server is the bridge between your AI coding agent and the fifteen-plus telemetry types Datadog already collects from your stack — logs, metrics, traces, RUM sessions, synthetic checks, and monitor state. Instead of tabbing between Claude Code and the Datadog UI, copying a trace ID here, a log query there, you let the agent pull the data directly into the conversation where it's reasoning about your incident or your code change. The official server ships as @datadog/datadog-mcp-server on npm, and Datadog also documents a hosted remote MCP endpoint for accounts on modern pricing tiers. Both expose the same core toolset; the difference is whether you run the process locally (stdio) or point your agent at Datadog's hosted URL (SSE/HTTP transport).

This topic covers what the server actually exposes, how authentication is scoped, what parts of an investigation genuinely benefit from AI assistance versus what still needs a human, and — because this is metered API usage against a paid observability platform — how to avoid a rate-limit wall or a surprise line item on next month's Datadog bill.

Core Datadog MCP Tools: Logs, Metrics, Monitors, APM Traces, and Dashboards

The MCP server groups its tools roughly by Datadog product area. You won't get every API endpoint Datadog exposes — the surface is curated for the query-and-diagnose workflow, not for administrative tasks like creating new monitors from scratch (some servers add write tools, but treat those as an opt-in, not a given).

Logs. The primary tool is a log search that accepts Datadog's native query syntax — the same string you'd type into the Log Explorer search bar:

service:checkout-api status:error @http.status_code:500 -env:staging

The agent translates your English question ("show me 5xx errors from checkout in the last hour, excluding staging") into that syntax, calls the tool, and gets back a paginated list of log events with attributes, tags, and timestamps. It can also request log facets and aggregations, which matters when you want a count-by-service breakdown rather than raw event dumps.

Metrics. Metric tools accept Datadog's metric query language:

avg:trace.express.request.duration{service:checkout-api} by {resource_name}

or for infrastructure:

avg:system.cpu.user{host:i-0abc123} rollup(avg, 300)

The server returns time series points, not just a scalar, so the agent can reason about trends — "did p99 latency climb steadily or spike at a single timestamp" is a materially different diagnosis, and the agent can only tell you which one happened if it has the actual series.

Monitors. Monitor tools list monitor definitions, current status (OK, Alert, Warn, No Data), and recent state transitions. This is what makes "why did monitor X fire" a tractable AI question — the agent reads the monitor's query, evaluates it against current data, and cross-references the alert timestamp against logs and traces from the same window.

APM traces. Trace tools query spans by service, resource, operation name, and trace ID, and can pull the full waterfall for a specific trace_id. This is the single most useful capability for code-level debugging because it's the one dataset that maps directly onto function calls and file paths in your repo.

Dashboards. Dashboard tools are mostly read-only: list dashboards, fetch a dashboard's widget definitions and underlying queries. Useful for "what does the on-call runbook dashboard actually measure" rather than for building new dashboards — dashboard authoring via MCP is thin or absent depending on server version, so don't plan a workflow around AI-generated dashboards yet.

npx -y @datadog/datadog-mcp-server

Tips
- Ask the agent to show you the raw Datadog query it built before running it once, early on — it teaches you the syntax mapping and catches quantity mistakes (e.g., querying 1h when you meant 24h) before they burn your log-scan quota.
- Trace tools are the highest-leverage tool group for developers specifically, because trace metadata (service, resource, dd.trace_id) links straight back to your codebase; treat logs/metrics as context and traces as the connective tissue.
- Dashboard tools are read-heavy today — don't expect the agent to redesign a dashboard for you reliably yet.

Datadog MCP Authentication: API Key, App Key, and Site Region Config

Datadog splits credentials into two keys, and the MCP server needs both — this trips people up constantly because a plain API key is enough for ingestion but not for querying.

  • API key (DD_API_KEY) — identifies your organization, used for data ingestion and some read calls.
  • Application key (DD_APP_KEY) — scoped to a specific user, required for most query and search endpoints (logs search, APM query, monitor read). Application keys inherit the permissions of the user who created them, so a key from a read-only "observer" role account is the safest choice for an AI agent with tool-calling access.
  • Site (DD_SITE) — Datadog runs separate regional instances (datadoghq.com US1, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu EU1, ap1.datadoghq.com, ddog-gov.com). Pointing at the wrong site is the number one "why is my agent getting empty results" bug — the keys are valid, the org just doesn't exist on that site.

Generate both keys from Organization Settings → API Keys and Organization Settings → Application Keys in the Datadog UI. Then wire them into your MCP client config:

{
  "mcpServers": {
    "datadog": {
      "command": "npx",
      "args": ["-y", "@datadog/datadog-mcp-server"],
      "env": {
        "DD_API_KEY": "your-api-key",
        "DD_APP_KEY": "your-app-key",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}

Never hardcode these in a file that gets committed. Use your shell environment or a secrets manager and reference the variable, or — for Claude Code specifically — store them in .claude/settings.local.json (already gitignored by default) rather than the shared .claude/settings.json.

For the hosted remote MCP endpoint, Datadog issues a URL scoped to your org and role instead of raw keys embedded in client config, which is the safer option for shared/team setups since revocation happens centrally in the Datadog UI without touching every developer's local config.

{
  "mcpServers": {
    "datadog-remote": {
      "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp",
      "headers": {
        "Authorization": "Bearer ${DATADOG_MCP_TOKEN}"
      }
    }
  }
}

Check current exact endpoint and header names against Datadog's docs at setup time — this is an area still marked "preview/unstable" in Datadog's own naming, and paths shift between releases.

Tips
- Create a dedicated Datadog "service account" or a low-privilege user solely for the app key used by AI agents — never reuse your own personal app key, since every query the agent runs shows up in audit logs under that identity.
- DD_SITE mismatches produce empty results, not errors — if queries return nothing for data you know exists, check the site first.
- Rotate the app key on a schedule (90 days is a reasonable default) since it's now embedded in a config file that could linger in shell history or a synced dotfiles repo.

What AI Can Automate: Query Building, Correlation, and Incident Summaries

The honest value proposition here isn't "AI replaces observability engineering" — it's that AI collapses the translation step between a vague human question and the precise query language Datadog needs.

Query building. "What's causing checkout to be slow since 2pm" becomes a metric query for trace.express.request.duration, a log search filtered to the checkout service and error status, and possibly a monitor status check — all without you recalling the exact tag names your team uses (service:checkout-api vs service:checkout_api vs svc:checkout, and yes, tag inconsistency across teams is a real and common problem the agent will surface for you).

Correlation. This is where MCP earns its keep over the plain Datadog UI. A single prompt can ask the agent to pull the monitor's alert query results, fetch APM traces for the same service in the same time window, cross-reference against a deploy marker, and check infrastructure metrics for the underlying hosts — four separate UI tabs, one conversation turn. The agent does the join manually by passing shared identifiers (service name, time window, host tag) between tool calls; there's no magic join engine, just sequential tool calls with the output of one feeding the query of the next.

Incident summaries. Once the agent has pulled logs, traces, and monitor data, asking it to draft a timeline ("what happened, in order, with timestamps") is genuinely strong — LLMs are good at turning disparate timestamped events into coherent narrative, and that narrative is a solid first draft for a postmortem doc. It is a draft, though. Verify every timestamp and every causal claim against the source data before it goes in a doc that gets circulated — LLMs will occasionally imply causation between two events that were merely close in time.

Example prompt that exercises all three:

Our checkout-latency monitor fired at 14:32 UTC today. Pull the monitor's
query results, find the top 3 slowest APM traces for checkout-api in the
window 14:15-14:45, check for any deploy markers in that range, and give
me a timeline of what happened.

Tips
- Give the agent the exact monitor name or ID rather than a vague description — Datadog orgs commonly have dozens of similarly-named monitors, and the agent will guess wrong silently if you're ambiguous.
- Treat AI-drafted incident summaries as a first draft for a human reviewer, never as the final postmortem text — verify causal claims against raw timestamps.
- Correlation quality depends entirely on consistent tagging across your services; if env, service, and version tags aren't applied uniformly, tell the agent about the inconsistency up front so it doesn't silently miss data under a differently-tagged service.

Cost and Rate Limit Awareness When an Agent Queries Observability Data

Datadog APIs are rate-limited per organization, per endpoint, typically in the range of a few hundred to a couple thousand requests per hour depending on the endpoint and your plan — the Logs Search API and Metrics Query API are the ones you'll hit first under agentic use, because an agent doing exploratory investigation issues many more small queries than a human clicking through a dashboard would. Datadog returns 429 with a Retry-After header when you're throttled; a well-behaved MCP server should back off and retry, but not all implementations do that gracefully, so watch for the agent reporting repeated failures during a heavy investigation session.

The bigger, quieter risk is cost, not rate limits. Datadog log-based metrics, log indexing, and custom metrics are billed on ingested/indexed volume — querying doesn't usually cost extra directly on standard plans, but an agent that runs a broad, unscoped log search across a 30-day window on a high-volume service can return an enormous result set, and if your workflow pipes that into something that generates custom metrics or triggers additional indexing, costs compound in ways that aren't obvious from a single query.

Practical scoping habits:

service:checkout-api status:error @env:production

instead of an unscoped:

status:error

Unscoped queries across all services can return results so broad the agent's summary becomes noise, and — on log-heavy accounts — can also be genuinely slow, timing out the tool call.

Time windows matter as much as service scope. Default to the smallest window that could plausibly contain the incident (last 1-4 hours), and only widen it if the agent's first pass comes back empty. An agent instructed with "check the last 30 days" for what turns out to be a 20-minute incident will burn far more of your rate-limit budget and return so much data that the model's own context window becomes the bottleneck before Datadog's API does.

Tips
- Default every log/metric query to a 1-4 hour window and a specific service: tag; widen deliberately, never by default.
- If you're on a metered log-indexing plan, an agent-driven investigation loop that keeps re-running broad searches can indirectly nudge your indexing costs — review your Datadog usage dashboard after enabling heavy MCP-driven workflows for the first week.
- Watch for 429 responses in the agent's tool output; if you see repeated throttling, add explicit rate-limit guidance to your system prompt (e.g., "wait between queries, don't issue more than 3 log searches per minute") rather than relying on the server to self-throttle.

Tips

Tips
- Start every new Datadog MCP setup with a single scoped query (one service, one hour) to confirm the API key, app key, and site are all correct before trusting the agent with an open-ended investigation.
- Use a dedicated, low-privilege Datadog user for the application key so agent-driven queries are auditable and easy to revoke independently of any human's credentials.
- Treat AI-generated correlation and incident timelines as strong first drafts, not verified fact — the underlying tool calls are real API responses, but the narrative stitching them together is inference.
- Budget for rate limits and log-indexing costs the same way you'd budget for any automated system hitting a metered API — scope queries tightly by default.

Next Datadog MCP With Claude Code CLI and VS Code