datadog mcp

Instructions

Implementation Reference

• src/tools/aggregateLogs.ts:51-101 (handler)

  The execute function that handles the tool logic: destructures params, constructs the API URL for Datadog logs aggregate endpoint, sends POST request with fetch, handles response and errors.

  execute: async (params: AggregateLogsParams) => {
    try {
      const { filter, compute, groupBy, options } = params;
  
      // Directly call with fetch to use the documented aggregation endpoint
      const apiUrl = `https://${
        process.env.DD_LOGS_SITE || "datadoghq.com"
      }/api/v2/logs/analytics/aggregate`;
  
      const headers = {
        "Content-Type": "application/json",
        "DD-API-KEY": process.env.DD_API_KEY || "",
        "DD-APPLICATION-KEY": process.env.DD_APP_KEY || ""
      };
  
      const body = {
        filter: filter,
        compute: compute,
        group_by: groupBy,
        options: options
      };
  
      const response = await fetch(apiUrl, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(body)
      });
  
      if (!response.ok) {
        throw {
          status: response.status,
          message: await response.text()
        };
      }
  
      const data = await response.json();
      return data;
    } catch (error: any) {
      if (error.status === 403) {
        console.error(
          "Authorization failed (403 Forbidden): Check that your API key and Application key are valid and have sufficient permissions to access log analytics."
        );
        throw new Error(
          "Datadog API authorization failed. Please verify your API and Application keys have the correct permissions."
        );
      } else {
        console.error("Error aggregating logs:", error);
        throw error;
      }
    }
  }

• src/index.ts:244-290 (registration)

  Registers the 'aggregate-logs' tool with MCP server: defines name, description, Zod input schema, and async handler that calls aggregateLogs.execute and formats response.

  server.tool(
    "aggregate-logs",
    "Perform analytical queries and aggregations on log data. Essential for calculating metrics (count, avg, sum, etc.), grouping data by fields, and creating statistical summaries from logs. Use this when you need to analyze patterns or extract metrics from log data.",
    {
      filter: z
        .object({
          query: z.string().optional(),
          from: z.string().optional(),
          to: z.string().optional(),
          indexes: z.array(z.string()).optional()
        })
        .optional(),
      compute: z
        .array(
          z.object({
            aggregation: z.string(),
            metric: z.string().optional(),
            type: z.string().optional()
          })
        )
        .optional(),
      groupBy: z
        .array(
          z.object({
            facet: z.string(),
            limit: z.number().optional(),
            sort: z
              .object({
                aggregation: z.string(),
                order: z.string()
              })
              .optional()
          })
        )
        .optional(),
      options: z
        .object({
          timezone: z.string().optional()
        })
        .optional()
    },
    async (args) => {
      const result = await aggregateLogs.execute(args);
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      };
    }

• src/tools/aggregateLogs.ts:3-26 (schema)

  TypeScript type definition for the input parameters of the aggregate-logs tool, matching the Zod schema used in registration.

  type AggregateLogsParams = {
    filter?: {
      query?: string;
      from?: string;
      to?: string;
      indexes?: string[];
    };
    compute?: Array<{
      aggregation: string;
      metric?: string;
      type?: string;
    }>;
    groupBy?: Array<{
      facet: string;
      limit?: number;
      sort?: {
        aggregation: string;
        order: string;
      };
    }>;
    options?: {
      timezone?: string;
    };
  };

• src/tools/aggregateLogs.ts:31-49 (helper)

  Initializes the Datadog API client configuration with auth keys and logs site, enabling unstable operations for logs aggregation.

  initialize: () => {
    const configOpts = {
      authMethods: {
        apiKeyAuth: process.env.DD_API_KEY,
        appKeyAuth: process.env.DD_APP_KEY
      }
    };
  
    configuration = client.createConfiguration(configOpts);
  
    if (process.env.DD_LOGS_SITE) {
      configuration.setServerVariables({
        site: process.env.DD_LOGS_SITE
      });
    }
  
    // Enable any unstable operations
    configuration.unstableOperations["v2.aggregateLogs"] = true;
  },