MCP Server Datadog — query metrics, list monitors, post events, and /health via API key validate

SDK setup and authentication

The official @datadog/datadog-api-client npm package provides full TypeScript types for every Datadog API version. It handles header injection, response parsing, and server variable substitution for multi-site support. For lightweight integrations, raw axios also works — you just need to set both authentication headers manually on every request.

import { client, v1, v2 } from '@datadog/datadog-api-client';

const configuration = client.createConfiguration({
  authMethods: {
    apiKeyAuth: process.env.DD_API_KEY!,
    appKeyAuth: process.env.DD_APP_KEY!,
  },
  // For EU customers: override the site variable
  // serverVariables: { site: 'datadoghq.eu' }
});

const metricsApi = new v1.MetricsApi(configuration);
const monitorsApi = new v1.MonitorsApi(configuration);
const eventsApi = new v2.EventsApi(configuration);

// If using raw axios instead of the SDK:
import axios from 'axios';

const ddHttp = axios.create({
  baseURL: 'https://api.datadoghq.com',
  headers: {
    'DD-API-KEY': process.env.DD_API_KEY!,
    'DD-APPLICATION-KEY': process.env.DD_APP_KEY!,
    'Content-Type': 'application/json',
  }
});
// EU customers: baseURL: 'https://api.datadoghq.eu'

Application Keys are scoped to the user who created them — they inherit that user's role permissions in Datadog. If the key owner's permissions change, API reads silently return 403. Use a dedicated service account user and its Application Key for MCP server credentials to decouple permissions from individual team members.

Querying timeseries metrics with query_metrics

The v1.MetricsApi.queryMetrics() method retrieves timeseries data for any Datadog metrics query string. The from and to parameters are Unix epoch seconds, but each point in the returned pointlist array uses millisecond timestamps — a common source of off-by-1000 bugs. The metrics query endpoint is rate-limited to 300 requests per hour, so avoid polling in tight loops.

server.tool('query_metrics', {
  from_time: z.number().int()
    .describe('Start of query window as Unix epoch seconds (e.g. Math.floor(Date.now()/1000) - 3600).'),
  to_time: z.number().int()
    .describe('End of query window as Unix epoch seconds.'),
  query: z.string()
    .describe('Datadog metrics query string, e.g. "avg:system.cpu.user{host:web-01}".')
}, async ({ from_time, to_time, query }) => {
  // queryMetrics takes from/to as seconds, not milliseconds
  const result = await metricsApi.queryMetrics({
    from: from_time,
    to: to_time,
    query,
  });

  // result.series is an array of matched timeseries
  const series = (result.series ?? []).map(s => ({
    metric: s.metric,
    scope: s.scope,
    // pointlist: array of [timestamp_ms, value] — timestamps ARE milliseconds
    points: (s.pointlist ?? []).map(([ts, val]) => ({
      timestamp_ms: ts,
      timestamp_iso: new Date(ts).toISOString(),
      value: val,
    })),
    start: s.start,
    end: s.end,
    interval: s.interval,
  }));

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({ query, from_time, to_time, series }, null, 2)
    }]
  };
});

Datadog automatically selects a rollup interval based on how long your query window spans. For a 1-hour window you get ~1-minute intervals; for a 7-day window you get ~1-hour intervals. If you need finer resolution, use the rollup() function in your query string: avg:system.cpu.user{*}.rollup(avg, 60) forces 60-second intervals.

Listing and muting monitors with list_monitors and mute_monitor

v1.MonitorsApi.listMonitors() returns all monitors in your account, with optional filtering by name substring or tags. Monitor tags use OR logic when comma-separated — passing env:prod,team:platform returns monitors tagged with either. Muting suppresses notifications without resolving the alert: a muted monitor can still change state, it just won't page anyone. Always add a confirm guard before muting.

server.tool('list_monitors', {
  tags: z.string().optional()
    .describe('Comma-separated monitor tags to filter by (OR logic). E.g. "env:prod,team:platform".'),
  name: z.string().optional()
    .describe('Filter monitors whose name contains this substring.'),
  monitor_states: z.array(
    z.enum(['Alert', 'Warn', 'OK', 'No Data', 'Ignored', 'Skipped', 'Unknown'])
  ).optional().describe('Only return monitors currently in these states.')
}, async ({ tags, name, monitor_states }) => {
  const monitors = await monitorsApi.listMonitors({ tags, name });

  const filtered = monitor_states
    ? monitors.filter(m => monitor_states.includes(m.overallState as any))
    : monitors;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify(
        filtered.map(m => ({
          id: m.id,
          name: m.name,
          type: m.type,
          state: m.overallState,
          tags: m.tags,
          created: m.created,
          modified: m.modified,
        })),
        null, 2
      )
    }]
  };
});

server.tool('mute_monitor', {
  id: z.number().int().describe('Datadog monitor ID to mute.'),
  end: z.number().int().optional()
    .describe('Unix epoch seconds when the mute should lift. Omit to mute indefinitely.'),
  confirm: z.literal(true)
    .describe('Muting suppresses notifications but does not resolve the alert. Pass true to confirm.')
}, async ({ id, end }) => {
  // POST /api/v1/monitor/:id/mute — mutes the monitor
  // omitting end in the body mutes indefinitely
  const body = end !== undefined ? { end } : {};
  const result = await monitorsApi.muteMonitor({ monitorId: id, body });

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        id: result.id,
        name: result.name,
        muted_until: end ? new Date(end * 1000).toISOString() : 'indefinitely',
        state: result.overallState,
      }, null, 2)
    }]
  };
});

Posting deployment events with post_event

The Datadog event stream is a timestamped log of significant occurrences — deployments, config changes, incidents, and custom annotations. Events can trigger event-based monitors and appear as overlays on metric graphs, making them critical for correlating metric spikes with deploys. The v2 EventsApi is the current interface; the v1 /api/v1/events endpoint also works and only requires an API key (no Application key needed).

server.tool('post_event', {
  title: z.string().max(100).describe('Event title — keep concise, shown in the event stream.'),
  text: z.string().max(4000)
    .describe('Event body. Supports Markdown. Include git SHA, deploy target, and timestamp.'),
  priority: z.enum(['normal', 'low']).default('normal')
    .describe('"normal" events appear in the stream; "low" events are aggregated.'),
  alert_type: z.enum(['info', 'warning', 'error', 'success']).default('info')
    .describe('Sets the event color and icon in the Datadog UI.'),
  tags: z.array(z.string()).optional()
    .describe('Tags to attach, e.g. ["env:prod", "service:api", "version:1.4.2"].')
}, async ({ title, text, priority, alert_type, tags }) => {
  // v1 events endpoint — only requires DD-API-KEY, no Application key needed
  const result = await ddHttp.post('/api/v1/events', {
    title,
    text,
    priority,
    alert_type,
    tags: tags ?? [],
    // source_type_name can help categorize events — e.g. 'my_apps', 'deploy'
  });

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        id: result.data.event?.id,
        url: result.data.event?.url,
        title,
        alert_type,
        priority,
        tags,
        // Tip: include git SHA in text for deploy correlation:
        // text: `Deploy v1.4.2 (${gitSha}) to prod by ${user}`
      }, null, 2)
    }]
  };
});

Tagging events with version:<git-sha> and env:prod lets you overlay deploy markers on metric graphs in Datadog dashboards. When you see a CPU spike, you can immediately check whether a deploy event was posted at the same timestamp.

Wiring /health/datadog via the validate endpoint

The Datadog health probe has a subtlety: GET /api/v1/validate only validates the DD-API-KEY header — it does not check the Application key. A server where the API key is valid but the Application key is revoked will pass the validate check and then silently return 403 on every metrics query. The robust approach validates both independently.

app.get('/health/datadog', async (req, res) => {
  const checks: Record<string, unknown> = {};

  // Step 1: validate the API key via /api/v1/validate
  try {
    const validateRes = await ddHttp.get('/api/v1/validate');
    // Returns { valid: true } on success, 403 if invalid
    checks.api_key = validateRes.data.valid === true ? 'valid' : 'invalid';
  } catch (err: any) {
    checks.api_key = `invalid (HTTP ${err.response?.status})`;
    return res.status(503).json({ status: 'unhealthy', checks });
  }

  // Step 2: validate the Application key by making a lightweight read
  // GET /api/v1/monitor?page_size=1 requires the Application key
  try {
    await ddHttp.get('/api/v1/monitor', { params: { page_size: 1 } });
    checks.app_key = 'valid';
  } catch (err: any) {
    const status = err.response?.status;
    checks.app_key = status === 403
      ? 'invalid or insufficient permissions'
      : `error (HTTP ${status})`;
    return res.status(503).json({ status: 'unhealthy', checks });
  }

  return res.json({ status: 'healthy', checks });
});

Register this /health/datadog endpoint with AliveMCP and set a check interval of 60 seconds. When the validate endpoint returns 403, AliveMCP will alert immediately — catching rotated or expired API keys before your metrics pipeline loses ingest and your monitors stop evaluating.

Frequently asked questions

Further reading

• MCP Server AWS CloudWatch — query metrics, describe alarms, and health probes via CloudWatch
• MCP Server Health Check — wiring /health endpoints for uptime monitoring
• MCP Server Error Handling — structured errors and retry patterns for MCP tools
• MCP Server Webhook Alerts — sending alert payloads to Slack, PagerDuty, and custom endpoints
• Building MCP Tools for DevOps Platforms — patterns for CI/CD, observability, and incident response