mcp-datadog-server

Servidor MCP de Datadog

Documentación

MCP Datadog Server

Servidor MCP (Model Context Protocol) completo y robusto para integración con APIs de Datadog

Un servidor MCP de producción que ofrece 351 tools para interactuar con todas las APIs de Datadog a través de LLMs, incluyendo operaciones CRUD completas, tools curadas y herramientas generadas automáticamente del schema.

🚀 Características Principales

📊 Tools Disponibles (351 total)

9 Tools Curadas 🎯 - Handcrafted, optimizadas para casos específicos
25 Tools CRUD ⚡ - Operaciones CREATE, READ, UPDATE, DELETE para recursos principales
319 Tools Generadas 🔧 - Generadas automáticamente del schema oficial de Datadog

🔍 Recursos Avanzados

✅ Autodescubrimiento de Schema - Los LLMs descubren parámetros automáticamente
✅ Validación Robusta - Zod schemas con validación completa
✅ Progress Tracking - Seguimiento en tiempo real para operaciones largas
✅ Error Handling - Manejo inteligente de errores y retry automático
✅ CLI Rica - Interfaz completa para gestión y debugging

🛡️ Conformidad MCP

✅ 100% Compatible con TypeScript SDK oficial
✅ JSON Schema completo para todas las tools
✅ Metadata Annotations detalladas
✅ Type Safety con validación Zod

📦 Instalación

Requisitos

Node.js 18+
Claves de API de Datadog (API Key + Application Key)

Instalación vía npm

npm install -g mcp-datadog-server

Instalación Local

git clone https://github.com/ClaudioLazaro/mcp-datadog-server.git
cd mcp-datadog-server
npm install

⚙️ Configuración

1. Variables de Entorno

Obligatorias

DD_API_KEY=your_api_key         # Chave da API Datadog
DD_APP_KEY=your_app_key         # Chave da aplicação Datadog

Opcionales

DD_SITE=datadoghq.com           # Site Datadog (padrão: datadoghq.com)
DD_SUBDOMAIN=api                # Subdomínio (padrão: api)
MCP_DD_FOLDERS=Dashboards,Logs  # Categorias permitidas (padrão: todas)
MCP_DD_SCHEMA_PATH=./schema.json # Caminho do schema (padrão: incluído)
MCP_DD_MAX_RETRIES=3            # Máximo de tentativas (padrão: 3)
MCP_DD_RETRY_BASE_MS=1000       # Base para retry em ms (padrão: 1000)
MCP_DD_TIMEOUT_MS=30000         # Timeout das requisições (padrão: 30000)
MCP_DD_USER_AGENT=mcp-datadog   # User agent customizado

2. Archivo .env (Recomendado)

# .env
DD_SITE=\"us3.datadoghq.com\"
DD_API_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxx\"
DD_APP_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"
MCP_DD_FOLDERS=\"Dashboards,Monitors,Logs\"

3. Sitios Datadog Soportados

datadoghq.com (US1)
datadoghq.eu (EU)
us3.datadoghq.com (US3)
us5.datadoghq.com (US5)
ap1.datadoghq.com (AP1)
ddog-gov.com (US Gov)

🎮 Uso

Servidor MCP (Estándar)

# Iniciar servidor MCP
mcp-datadog-server serve
# ou
npm start

# Com filtros
mcp-datadog-server serve --folders=Dashboards,Monitors

Interfaz CLI

Listar Tools

# Lista básica
mcp-datadog-server list-tools

# Lista detalhada ordenada
mcp-datadog-server list-tools --detailed

# JSON output
mcp-datadog-server list-tools --json

Inspección de Tools

# Ver detalhes de uma tool
mcp-datadog-server get-tool create_monitor

# Ver schema completo de uma tool
mcp-datadog-server show-schema create_monitor

# JSON output
mcp-datadog-server show-schema create_monitor --json

Validación y Análisis

# Validar configuração
mcp-datadog-server validate

# Analisar schema da API
mcp-datadog-server analyze-schema

# Ajuda
mcp-datadog-server help

🔧 Tools CRUD Disponibles

⚡ Monitors (5 operaciones)

create_monitor    # Criar novo monitor
get_monitor       # Obter monitor por ID
update_monitor    # Atualizar monitor existente
delete_monitor    # Deletar monitor
list_monitor      # Listar todos os monitors

📊 Dashboards (5 operaciones)

create_dashboard  # Criar novo dashboard
get_dashboard     # Obter dashboard por ID
update_dashboard  # Atualizar dashboard existente
delete_dashboard  # Deletar dashboard
list_dashboard    # Listar todos os dashboards

⏰ Downtimes (5 operaciones)

create_downtime   # Agendar downtime
get_downtime      # Obter downtime por ID
update_downtime   # Atualizar downtime
delete_downtime   # Cancelar downtime
list_downtime     # Listar todos os downtimes

👥 Users (5 operaciones)

create_user       # Criar usuário
get_user          # Obter usuário por ID
update_user       # Atualizar usuário
delete_user       # Deletar usuário
list_user         # Listar todos os usuários

🏗️ Teams (5 operaciones)

create_team       # Criar equipe
get_team          # Obter equipe por ID
update_team       # Atualizar equipe
delete_team       # Deletar equipe
list_team         # Listar todas as equipes

📋 Cómo el LLM Descubre los Parámetros

🔍 Autodescubrimiento Automático

El LLM NO necesita saber los parámetros de antemano. A través del protocolo MCP, él:

Lista todas las tools disponibles
Obtiene el schema JSON Schema completo de cada tool
Entiende todos los parámetros, tipos y validaciones
Construye llamadas válidas automáticamente

📄 Schema Ejemplo - create_monitor

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Monitor name"
    },
    "type": {
      "type": "string",
      "enum": ["metric alert", "service check", "event alert", "query alert", "composite", "log alert"],
      "description": "Monitor type"
    },
    "query": {
      "type": "string",
      "description": "Monitor query"
    },
    "message": {
      "type": "string",
      "description": "Notification message"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Monitor tags"
    },
    "priority": {
      "type": "number",
      "minimum": 1,
      "maximum": 5,
      "description": "Priority (1-5)"
    },
    "options": {
      "type": "object",
      "properties": {
        "thresholds": {
          "type": "object",
          "properties": {
            "critical": {"type": "number"},
            "warning": {"type": "number"},
            "ok": {"type": "number"}
          }
        },
        "notify_audit": {"type": "boolean"},
        "require_full_window": {"type": "boolean"}
      }
    }
  },
  "required": ["name", "type", "query"]
}

🎯 Ejemplo de Uso por el LLM

Entrada del usuario:

"Crear un monitor para alertar cuando el uso de CPU esté por encima del 90%"

Llamada automática del LLM:

await use_tool("create_monitor", {
  "name": "High CPU Usage Alert",
  "type": "metric alert",
  "query": "avg(last_5m):avg:system.cpu.user{*} > 0.9",
  "message": "CPU usage is high! Please investigate @ops-team",
  "tags": ["alert", "cpu", "infrastructure"],
  "priority": 3,
  "options": {
    "thresholds": {
      "critical": 0.9,
      "warning": 0.8
    },
    "notify_audit": true,
    "require_full_window": false
  }
})

El LLM automáticamente:

✅ Descubrió todos los parámetros disponibles
✅ Rellenó campos obligatorios (name, type, query)
✅ Añadió campos opcionales relevantes
✅ Estructuró objetos complejos (options.thresholds)
✅ Validó tipos y constraints

🎯 Tools Curadas Especiales

🎯 Dashboards

list_dashboards   # Lista com filtros avançados e paginação

🎯 Logs

search_logs       # Busca avançada de logs com filtros

🎯 Metrics

query_metrics     # Query de métricas timeseries

🎯 Incidents

manage_incidents  # Gerenciamento completo de incidentes

🎯 Synthetics

manage_synthetics # Testes sintéticos completos

🏗️ Integración con LLMs

Claude Desktop (Recomendado)

Añada al archivo de configuración de Claude:

{
  "mcpServers": {
    "datadog": {
      "command": "mcp-datadog-server",
      "args": ["serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}

Vía npx (Global)

{
  "mcpServers": {
    "datadog": {
      "command": "npx",
      "args": ["-y", "mcp-datadog-server", "serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key"
      }
    }
  }
}

Desarrollo Local

{
  "mcpServers": {
    "datadog": {
      "command": "node",
      "args": ["/path/to/mcp-datadog-server/src/index.js", "serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key"
      }
    }
  }
}

🛠️ Desarrollo

Scripts Disponibles

npm test              # Executar testes
npm run serve         # Iniciar servidor
npm run list-tools    # Listar tools
npm run validate      # Validar configuração
npm run analyze-schema # Analisar schema da API

Makefile

make install          # Instalar dependências
make start           # Iniciar servidor
make test            # Executar testes
make list-tools      # Listar tools
make validate        # Validar configuração

Estructura del Proyecto

src/
├── index.js                    # CLI principal
├── server.js                   # Servidor MCP principal
├── core/
│   ├── config.js              # Sistema de configuração
│   ├── http-client.js         # Cliente HTTP com retry
│   ├── schema-parser.js       # Parser do schema Datadog
│   └── validation.js          # Validações robustas
└── tools/
    ├── core-tools.js          # Ferramentas base
    ├── curated-tools.js       # Tools curadas otimizadas
    └── crud-tools.js          # Tools CRUD automáticas

🔍 Debugging y Troubleshooting

Verificar Tools Cargadas

# Ver resumo
mcp-datadog-server list-tools

# Ver lista completa ordenada
mcp-datadog-server list-tools --detailed

# Ver schema de uma tool específica
mcp-datadog-server show-schema create_monitor

Validar Configuración

# Validar tudo
mcp-datadog-server validate

# Ver configuração resumida
mcp-datadog-server validate --json

Probar Conectividad

# Analisar schema carregado
mcp-datadog-server analyze-schema

# Testar servidor básico
timeout 5s mcp-datadog-server serve

Logs y Debugging

# O servidor gera logs estruturados:
[2025-01-20T10:30:00.000Z] [INFO] Starting server with config: {...}
[2025-01-20T10:30:01.000Z] [INFO] Registered 9 curated tools
[2025-01-20T10:30:02.000Z] [INFO] Registered 25 CRUD tools
[2025-01-20T10:30:03.000Z] [INFO] Registered 319 generated tools
[2025-01-20T10:30:04.000Z] [INFO] Registered 351 tools total

🚨 Solución de Problemas Comunes

1. "Tool no encontrada"

# Verificar se a tool existe
mcp-datadog-server list-tools --detailed | grep nome_da_tool

# Ver todas as categorias disponíveis
mcp-datadog-server analyze-schema

2. "API Key inválida"

# Validar credenciais
mcp-datadog-server validate

# Verificar variáveis de ambiente
echo $DD_API_KEY
echo $DD_APP_KEY

3. "Schema no cargado"

# Verificar se o schema existe
mcp-datadog-server analyze-schema

# Forçar recarregamento
rm -f datadog-api-collection-schema.json
mcp-datadog-server serve

4. "Demasiadas tools cargadas"

# Filtrar apenas categorias necessárias
export MCP_DD_FOLDERS="Dashboards,Monitors,Logs"
mcp-datadog-server list-tools

📈 Rendimiento y Límites

Rate Limiting

✅ Automático - Respeta headers retry-after
✅ Configurable - Ajuste vía MCP_DD_MAX_RETRIES
✅ Inteligente - Backoff exponencial

Timeouts

✅ Por defecto: 30 segundos por solicitud
✅ Configurable vía MCP_DD_TIMEOUT_MS
✅ Progress Tracking para operaciones largas

Uso de Memoria

✅ Optimizado - Schema cargado una vez en la inicialización
✅ Streaming - No mantiene responses grandes en memoria
✅ Filtros - Use MCP_DD_FOLDERS para reducir footprint

🔐 Seguridad

Credenciales

✅ Solo Entorno - Claves solo vía variables de entorno
✅ Sin Logging - Las credenciales nunca aparecen en logs
✅ Validación - Formato de las claves validado en la inicialización

Red

✅ Solo TLS - Todas las llamadas vía HTTPS
✅ Proxy Corporativo - Soporte vía NODE_EXTRA_CA_CERTS
✅ Seguridad de Headers - User-Agent y headers apropiados

Validación de Entrada

✅ Zod Schemas - Validación rigurosa de entrada
✅ Sanitización - Limpieza automática de inputs
✅ Type Safety - TypeScript + validación en runtime

📊 Monitoreo

Health Checks

# Status do servidor
mcp-datadog-server validate

# Análise das tools
mcp-datadog-server list-tools --json | jq '.total'

Métricas Disponibles

✅ Tools Count - Total de tools cargadas
✅ API Calls - Tracking de llamadas por tool
✅ Error Rate - Tasa de errores por categoría
✅ Response Time - Tiempos de respuesta medios

🎓 Ejemplos Prácticos

Crear Monitor de CPU

El LLM puede ejecutar automáticamente:

await use_tool("create_monitor", {
  name: "High CPU Alert",
  type: "metric alert",
  query: "avg(last_5m):avg:system.cpu.user{*} > 0.9",
  message: "CPU high @ops-team"
});

Listar Dashboards Filtrados

await use_tool("list_dashboard", {
  filter_shared: false,
  count: 50
});

Crear Downtime para Mantenimiento

await use_tool("create_downtime", {
  scope: ["host:web-server-01"],
  start: Math.floor(Date.now() / 1000),
  end: Math.floor(Date.now() / 1000) + 3600,
  message: "Planned maintenance window"
});

📚 Documentación Adicional

🔍 SCHEMA_DISCOVERY.md - Cómo el LLM descubre parámetros
📋 REFACTOR_CHECKPOINT.md - Historial de la refactorización
⚙️ TOOLS.md - Documentación completa de las tools

🤝 Contribución

Reportar Bugs

# Gerar relatório de debug
mcp-datadog-server validate --json > debug-info.json
mcp-datadog-server list-tools --json >> debug-info.json

Añadir Tools Curadas

Edite src/tools/curated-tools.js
Añada schema Zod completo
Implemente función execute
Pruebe con npm test

Mejorar Tools CRUD

Edite src/tools/crud-tools.js
Añada nuevos recursos al DATADOG_RESOURCES
Defina schemas y operaciones
Pruebe todas las operaciones CRUD

📝 Changelog

v0.3.0 - Actual

✅ 351 tools (9 curadas + 25 CRUD + 319 generadas)
✅ CRUD completo para recursos principales
✅ Schema autodescubrimiento vía MCP
✅ Progress tracking para operaciones largas
✅ CLI rica con comandos de debugging
✅ 100% conformidad con estándares MCP

v0.2.x - Anterior

✅ Refactorización completa de la arquitectura
✅ Validación robusta con Zod
✅ Cliente HTTP con retry automático
✅ Sistema de configuración limpio

📄 Licencia

Apache License 2.0 - Vea LICENSE para detalles.

🙏 Agradecimientos

Model Context Protocol - Framework base
Datadog - APIs y documentación
Zod - Validación de schema
Undici - Cliente HTTP

🎉 ¡Listo para usar con cualquier LLM compatible con MCP!

Para soporte y discusiones, vea las Issues del repositorio.