datadog-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Custom Datadog MCP (Model Context Protocol) server that gives Claude access to Datadog monitoring APIs. Replaces the limited community MCP server by adding time-series metrics queries, APM/Traces, RUM data, and full Datadog API coverage via the official SDK.

Tech Stack

• Runtime: Node.js 18+ with TypeScript (strict mode)
• Package Manager: pnpm
• MCP SDK: @modelcontextprotocol/sdk (^1.27.1)
• Datadog Client: @datadog/datadog-api-client (^1.59.0)
• Validation: zod
• Config: dotenv

Build & Run Commands

pnpm install          # Install dependencies
pnpm run build        # Compile TypeScript → dist/
pnpm run dev          # Watch mode (auto-rebuild)
node dist/index.js    # Run the MCP server

Architecture

This is an MCP server running as a subprocess, configured via .mcp.json. The data flow is:

Claude AI → MCP Protocol → index.ts (server) → tools/*.ts → Datadog API Client → Datadog API

Key Source Files

• src/index.ts — MCP server entry point, 156 tool registrations
• src/config.ts — Environment variable loading (DD_API_KEY, DD_APP_KEY, DD_SITE)
• src/client.ts — Datadog API client initialization using official SDK
• src/tools/utils.ts — wrapToolHandler error handling wrapper for all tools
• src/tools/ — One file per tool category, each exporting schema + handler

Tool Pattern

Each tool file follows the same pattern:

1. Define zod input schema with .describe() on every field
2. Call Datadog API via official SDK client
3. Transform response to a readable format
4. Handler is wrapped with wrapToolHandler() in index.ts for error handling

Tool Categories (156 tools)

File	Tools
metrics.ts	query-metrics, get-metrics, get-metric-metadata, list-active-metrics, list-metric-tags
monitors.ts	get-monitors, get-monitor, create-monitor, update-monitor, delete-monitor, mute-monitor, validate-monitor
dashboards.ts	get-dashboards, get-dashboard, create-dashboard, update-dashboard, delete-dashboard
logs.ts	search-logs, aggregate-logs, send-logs
events.ts	get-events, post-event
incidents.ts	get-incidents, get-incident, search-incidents, create-incident, update-incident, delete-incident
apm.ts	search-spans
rum.ts	search-rum-events, aggregate-rum, list-rum-applications, get-rum-application, create-rum-application, update-rum-application, delete-rum-application
rum-metrics.ts	list-rum-metrics, get-rum-metric, create-rum-metric, update-rum-metric, delete-rum-metric
rum-retention-filters.ts	list-rum-retention-filters, get-rum-retention-filter, create-rum-retention-filter, update-rum-retention-filter, delete-rum-retention-filter
hosts.ts	list-hosts, get-host-totals
slos.ts	list-slos, get-slo, get-slo-history
synthetics.ts	list-synthetics, get-synthetics-result, trigger-synthetics, create-synthetics-test, update-synthetics-test, delete-synthetics-test
downtimes.ts	list-downtimes, create-downtime, cancel-downtime
security.ts	search-security-signals, get-security-signal, list-security-rules, get-security-rule, delete-security-rule, list-security-suppressions, get-security-suppression, create-security-suppression, delete-security-suppression
account.ts	get-usage-summary, list-users
notebooks.ts	list-notebooks, get-notebook
oncall.ts	get-team-oncall, get-oncall-schedule
services.ts	list-services, get-service-definition
containers.ts	list-containers
processes.ts	list-processes
audit.ts	search-audit-logs
cases.ts	list-cases, get-case, create-case, update-case-status
errors.ts	list-error-tracking-issues, get-error-tracking-issue
ci.ts	search-ci-pipelines, aggregate-ci-pipelines, search-ci-tests, aggregate-ci-tests
networks.ts	list-network-devices, get-network-device
dora.ts	send-dora-deployment, send-dora-incident
teams.ts	list-teams, get-team, create-team, update-team, delete-team, get-team-members
logs-metrics.ts	list-logs-metrics, get-logs-metric, create-logs-metric, update-logs-metric, delete-logs-metric
spans-metrics.ts	list-spans-metrics, get-spans-metric, create-spans-metric, update-spans-metric, delete-spans-metric
slo-corrections.ts	list-slo-corrections, get-slo-correction, create-slo-correction, update-slo-correction, delete-slo-correction
apm-retention-filters.ts	list-apm-retention-filters, get-apm-retention-filter, create-apm-retention-filter, update-apm-retention-filter, delete-apm-retention-filter
status-pages.ts	list-status-pages, get-status-page, create-status-page, update-status-page, delete-status-page, publish-status-page, unpublish-status-page, list-status-page-components, get-status-page-component, create-status-page-component, update-status-page-component, delete-status-page-component, list-status-page-degradations, get-status-page-degradation, create-status-page-degradation, update-status-page-degradation, delete-status-page-degradation, list-status-page-maintenances, get-status-page-maintenance, create-status-page-maintenance, update-status-page-maintenance
fleet.ts	list-fleet-agents, get-fleet-agent-info, list-fleet-agent-versions, list-fleet-tracers, list-fleet-deployments, get-fleet-deployment, create-fleet-deployment-configure, create-fleet-deployment-upgrade, cancel-fleet-deployment, list-fleet-schedules, get-fleet-schedule, create-fleet-schedule, update-fleet-schedule, delete-fleet-schedule, trigger-fleet-schedule