Metrx MCP Server

Instructions

Implementation Reference

• src/tools/alert-config.ts:51-103 (handler)

  Handler function that executes the configure_alert_threshold tool logic. It constructs the API request path based on whether an agent_id is provided (for org-wide or agent-specific alerts), makes a POST request to the API, and formats the response with the configured threshold details.

  async ({ agent_id, metric, threshold_value, action }) => {
    const scope = agent_id ? `agent/${agent_id}` : 'org-wide';
    const path = agent_id ? `/agents/${agent_id}/alerts` : '/alerts/thresholds';
  
    const body: Record<string, unknown> = {
      metric,
      threshold_value,
      action,
    };
  
    const result = await client.post<{
      configured: boolean;
      threshold_id: string;
      message: string;
    }>(path, body);
  
    if (result.error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error configuring alert threshold: ${result.error}`,
          },
        ],
        isError: true,
      };
    }
  
    const data = result.data!;
    if (!data.configured) {
      return {
        content: [
          {
            type: 'text',
            text: `Alert configuration failed: ${data.message || 'Unknown reason'}`,
          },
        ],
        isError: true,
      };
    }
  
    const text = formatAlertConfigResponse(
      data.threshold_id,
      scope,
      metric,
      threshold_value,
      action
    );
  
    return {
      content: [{ type: 'text', text }],
    };
  }

• src/tools/alert-config.ts:24-43 (schema)

  Input schema definition for the configure_alert_threshold tool using zod. Validates agent_id (optional UUID), metric (enum: daily_cost, monthly_cost, error_rate, latency_p99), threshold_value (positive number), and action (enum: email, webhook, pause_agent).

  inputSchema: {
    agent_id: z
      .string()
      .uuid()
      .optional()
      .describe('Specific agent UUID to configure alerts for. Omit for org-wide alerts.'),
    metric: z
      .enum(['daily_cost', 'monthly_cost', 'error_rate', 'latency_p99'])
      .describe('Metric to monitor'),
    threshold_value: z
      .number()
      .positive()
      .describe(
        'Threshold value. For costs: cents (e.g., 500000 = $5000). ' +
          'For rates: decimal (e.g., 0.1 = 10%). For latency: ms.'
      ),
    action: z
      .enum(['email', 'webhook', 'pause_agent'])
      .describe('Action to trigger when threshold is breached'),
  },

• src/tools/alert-config.ts:15-104 (registration)

  Tool registration block where configure_alert_threshold is registered with the MCP server. Includes the tool metadata, description, inputSchema, annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), and the handler function.

  server.registerTool(
    'configure_alert_threshold',
    {
      title: 'Configure Alert Threshold',
      description:
        'Set up cost or operational alert thresholds for a specific agent or org-wide. ' +
        'Alerts can trigger email notifications, webhooks, or automatically pause the agent. ' +
        'Use for real-time cost governance and operational safety. Thresholds run server-side automatically. ' +
        'Do NOT use for viewing current alerts — use get_alerts instead.',
      inputSchema: {
        agent_id: z
          .string()
          .uuid()
          .optional()
          .describe('Specific agent UUID to configure alerts for. Omit for org-wide alerts.'),
        metric: z
          .enum(['daily_cost', 'monthly_cost', 'error_rate', 'latency_p99'])
          .describe('Metric to monitor'),
        threshold_value: z
          .number()
          .positive()
          .describe(
            'Threshold value. For costs: cents (e.g., 500000 = $5000). ' +
              'For rates: decimal (e.g., 0.1 = 10%). For latency: ms.'
          ),
        action: z
          .enum(['email', 'webhook', 'pause_agent'])
          .describe('Action to trigger when threshold is breached'),
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ agent_id, metric, threshold_value, action }) => {
      const scope = agent_id ? `agent/${agent_id}` : 'org-wide';
      const path = agent_id ? `/agents/${agent_id}/alerts` : '/alerts/thresholds';
  
      const body: Record<string, unknown> = {
        metric,
        threshold_value,
        action,
      };
  
      const result = await client.post<{
        configured: boolean;
        threshold_id: string;
        message: string;
      }>(path, body);
  
      if (result.error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error configuring alert threshold: ${result.error}`,
            },
          ],
          isError: true,
        };
      }
  
      const data = result.data!;
      if (!data.configured) {
        return {
          content: [
            {
              type: 'text',
              text: `Alert configuration failed: ${data.message || 'Unknown reason'}`,
            },
          ],
          isError: true,
        };
      }
  
      const text = formatAlertConfigResponse(
        data.threshold_id,
        scope,
        metric,
        threshold_value,
        action
      );
  
      return {
        content: [{ type: 'text', text }],
      };
    }
  );

• src/tools/alert-config.ts:110-160 (helper)

  Helper function formatAlertConfigResponse that formats the alert configuration confirmation into a readable markdown response. It formats threshold values based on metric type (costs in dollars, error_rate as percentage, latency_p99 as milliseconds) and describes the action behavior.

  function formatAlertConfigResponse(
    thresholdId: string,
    scope: string,
    metric: string,
    thresholdValue: number,
    action: string
  ): string {
    const lines: string[] = ['## Alert Threshold Configured', ''];
  
    lines.push(`**Threshold ID**: ${thresholdId}`);
    lines.push(`**Scope**: ${scope}`);
    lines.push(`**Metric**: ${metric}`);
  
    // Format threshold value based on metric type
    let thresholdDisplay = '';
    if (metric === 'daily_cost' || metric === 'monthly_cost') {
      thresholdDisplay = formatCents(thresholdValue);
    } else if (metric === 'error_rate') {
      thresholdDisplay = `${(thresholdValue * 100).toFixed(2)}%`;
    } else if (metric === 'latency_p99') {
      thresholdDisplay = `${thresholdValue.toFixed(0)}ms`;
    }
  
    lines.push(`**Threshold**: ${thresholdDisplay}`);
    lines.push(`**Action**: ${action}`);
    lines.push('');
  
    lines.push('### Behavior');
    switch (action) {
      case 'email':
        lines.push(
          'When the threshold is breached, an email notification will be sent to account owners.'
        );
        break;
      case 'webhook':
        lines.push(
          'When the threshold is breached, a POST request will be sent to configured webhook endpoints.'
        );
        break;
      case 'pause_agent':
        lines.push(
          'When the threshold is breached, the agent will be automatically paused to prevent further spend.'
        );
        break;
    }
  
    lines.push('');
    lines.push(`✅ Alert threshold is now active and being monitored in real-time.`);
  
    return lines.join('\n');
  }

• src/index.ts:74-103 (registration)

  Middleware wrapper in index.ts that automatically adds the 'metrx_' prefix to all tool registrations. The original 'configure_alert_threshold' becomes 'metrx_configure_alert_threshold'. Also wraps handlers with rate limiting (60 requests per minute).

  // ── Rate limiting middleware + metrx_ namespace prefix ──
  // All tools are registered exclusively as metrx_{name}.
  // The metrx_ prefix namespaces our tools to avoid collisions when
  // multiple MCP servers are used together.
  const METRX_PREFIX = 'metrx_';
  const originalRegisterTool = server.registerTool.bind(server);
  (server as any).registerTool = function (
    name: string,
    config: any,
    handler: (...handlerArgs: any[]) => Promise<any>
  ) {
    const wrappedHandler = async (...handlerArgs: any[]) => {
      if (!rateLimiter.isAllowed(name)) {
        return {
          content: [
            {
              type: 'text' as const,
              text: `Rate limit exceeded for tool '${name}'. Maximum 60 requests per minute allowed.`,
            },
          ],
          isError: true,
        };
      }
      return handler(...handlerArgs);
    };
  
    // Register with metrx_ prefix (only — no deprecated aliases)
    const prefixedName = name.startsWith(METRX_PREFIX) ? name : `${METRX_PREFIX}${name}`;
    originalRegisterTool(prefixedName, config, wrappedHandler);
  };