Metrx MCP Server

Instructions

Implementation Reference

• src/tools/alerts.ts:49-74 (handler)

  Main handler function for get_alerts tool that fetches alerts from the API, formats them using formatAlerts, and returns the response. Handles errors and processes the alerts list.

  async ({ severity, unread_only, limit }) => {
    const params: Record<string, string | number | boolean> = {
      limit: limit ?? 25,
    };
    if (severity) params.severity = severity;
    if (unread_only !== undefined) params.unread_only = unread_only;
  
    const result = await client.get<{ alerts: AlertEvent[] }>(
      '/alerts',
      params as Record<string, string>
    );
  
    if (result.error) {
      return {
        content: [{ type: 'text', text: `Error fetching alerts: ${result.error}` }],
        isError: true,
      };
    }
  
    const alerts = result.data?.alerts || [];
    const text = formatAlerts(alerts);
  
    return {
      content: [{ type: 'text', text }],
    };
  }

• src/tools/alerts.ts:16-75 (registration)

  Tool registration with name 'get_alerts', including input schema with severity, unread_only, and limit parameters, along with annotations and the handler function.

  server.registerTool(
    'get_alerts',
    {
      title: 'Get Alerts',
      description:
        'Get active alerts and notifications for your agent fleet. ' +
        'Includes cost spikes, error rate increases, budget warnings, ' +
        'and system health notifications. Optionally filter by severity. ' +
        'Do NOT use for configuring alert triggers — use configure_alert_threshold for that.',
      inputSchema: {
        severity: z
          .enum(['info', 'warning', 'critical'])
          .optional()
          .describe('Filter by alert severity'),
        unread_only: z
          .boolean()
          .default(true)
          .describe('Only return unread alerts (default: true)'),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .default(25)
          .describe('Maximum number of alerts to return'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ severity, unread_only, limit }) => {
      const params: Record<string, string | number | boolean> = {
        limit: limit ?? 25,
      };
      if (severity) params.severity = severity;
      if (unread_only !== undefined) params.unread_only = unread_only;
  
      const result = await client.get<{ alerts: AlertEvent[] }>(
        '/alerts',
        params as Record<string, string>
      );
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error fetching alerts: ${result.error}` }],
          isError: true,
        };
      }
  
      const alerts = result.data?.alerts || [];
      const text = formatAlerts(alerts);
  
      return {
        content: [{ type: 'text', text }],
      };
    }
  );

• src/tools/alerts.ts:25-41 (schema)

  Input schema definition using zod for validation of severity (enum), unread_only (boolean), and limit (number) parameters.

  inputSchema: {
    severity: z
      .enum(['info', 'warning', 'critical'])
      .optional()
      .describe('Filter by alert severity'),
    unread_only: z
      .boolean()
      .default(true)
      .describe('Only return unread alerts (default: true)'),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(25)
      .describe('Maximum number of alerts to return'),
  },

• src/types.ts:156-165 (schema)

  AlertEvent interface defining the type structure for alert objects including id, type, severity, title, message, agent_id, is_read, and created_at fields.

  export interface AlertEvent {
    id: string;
    type: string;
    severity: string;
    title: string;
    message: string;
    agent_id?: string;
    is_read: boolean;
    created_at: string;
  }

• src/services/formatters.ts:227-246 (helper)

  Helper function formatAlerts that formats an array of AlertEvent objects into a readable markdown string with severity icons, titles, messages, agent IDs, and timestamps.

  export function formatAlerts(alerts: AlertEvent[]): string {
    if (alerts.length === 0) {
      return 'No active alerts.';
    }
  
    const lines: string[] = [`## Active Alerts (${alerts.length})`, ''];
  
    for (const a of alerts) {
      const icon = a.severity === 'critical' ? '🔴' : a.severity === 'warning' ? '🟡' : 'ℹ️';
      lines.push(`${icon} **${a.title}** (${a.severity})`);
      lines.push(`  ${a.message}`);
      if (a.agent_id) {
        lines.push(`  Agent: ${a.agent_id}`);
      }
      lines.push(`  Time: ${a.created_at}`);
      lines.push('');
    }
  
    return lines.join('\n');
  }