datadog-mcp copilot-instructions.md

Datadog MCP Server - AI Agent Instructions

Architecture Overview

This is a FastMCP-based Model Context Protocol (MCP) server that exposes Datadog observability APIs to AI agents. The architecture centers on two core systems:

1. FastMCP Server (src/datadog_mcp_server.py) - HTTP+SSE transport server with tools, resources, and prompts
2. Key Rotation System (src/key_rotation.py) - Intelligent multi-key management for rate limit avoidance

Key Components

• DatadogMCPServer class: Main server with _execute_with_key_rotation() wrapper for all API calls
• KeyPoolManager: Manages 3-5 API key pairs with 5 rotation strategies (adaptive, round_robin, LRU, weighted, random)
• Circuit Breaker: Automatically isolates problematic keys after configurable failure threshold
• Debug System: Enum-based debug levels (NONE/INFO/DEBUG/TRACE) with correlation IDs and sensitive data masking

Critical Pattern: DD_SITE Must Always Come From Environment

NEVER hardcode Datadog site values. Always use environment variables:

# ✅ CORRECT - Always read from environment
site = os.getenv("DD_SITE") or os.getenv("DATADOG_SITE") or "us3.datadoghq.com"

# ✅ For numbered keys
site = os.getenv(f"DD_SITE_{i}") or os.getenv(f"DATADOG_SITE_{i}") or "us3.datadoghq.com"

# ❌ NEVER do this
site = "datadoghq.com"  # Wrong - hardcoded value

The default fallback us3.datadoghq.com should only appear in environment loading functions (load_keys_from_environment() in key_rotation.py), never in API client configuration.

Development Workflows

Running the Server

# Local development - reads .env file automatically
python3 src/datadog_mcp_server.py

# With debug tracing
MCP_DEBUG_LEVEL=TRACE python3 src/datadog_mcp_server.py

# Check server health on port 8080
curl http://localhost:8080/health

Testing

# Run all tests including key rotation
pytest tests/ -v

# Run specific test suite
pytest tests/test_key_rotation.py -v

# Test with coverage
pytest tests/ --cov=src --cov-report=html