Metrx MCP Server

Instructions

Implementation Reference

• src/tools/budgets.ts:33-48 (handler)

  Main handler function for get_budget_status tool. Fetches budget status from the API endpoint '/budgets/status', handles errors, and formats the response using formatBudgetStatus helper.

  async () => {
    const result = await client.get<BudgetStatus>('/budgets/status');
  
    if (result.error) {
      return {
        content: [{ type: 'text', text: `Error fetching budget status: ${result.error}` }],
        isError: true,
      };
    }
  
    const text = formatBudgetStatus(result.data!);
  
    return {
      content: [{ type: 'text', text }],
    };
  }

• src/tools/budgets.ts:16-49 (registration)

  Tool registration for 'get_budget_status'. Defines the tool metadata including title, description, input schema (empty - no parameters required), and annotations (readOnly, idempotent).

  server.registerTool(
    'get_budget_status',
    {
      title: 'Get Budget Status',
      description:
        'Get the current status of all budget configurations. ' +
        'Shows spending vs limits, warning/exceeded counts, and enforcement modes. ' +
        'Use this to monitor spending governance across your agent fleet. ' +
        'Do NOT use for creating/changing budgets — use set_budget or update_budget_mode.',
      inputSchema: {},
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async () => {
      const result = await client.get<BudgetStatus>('/budgets/status');
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error fetching budget status: ${result.error}` }],
          isError: true,
        };
      }
  
      const text = formatBudgetStatus(result.data!);
  
      return {
        content: [{ type: 'text', text }],
      };
    }
  );

• src/types.ts:89-109 (schema)

  Type definitions for BudgetStatus and BudgetSummary interfaces. BudgetStatus contains the response structure including has_budgets, total_budgets, warning_count, exceeded_count, paused_count, and budgets array.

  export interface BudgetStatus {
    has_budgets: boolean;
    total_budgets: number;
    paused_count: number;
    warning_count: number;
    exceeded_count: number;
    budgets: BudgetSummary[];
  }
  
  export interface BudgetSummary {
    id: string;
    period: string;
    agent_id: string | null;
    limit_microcents: number;
    spent_microcents: number;
    pct_used: number;
    enforcement_mode: string;
    paused: boolean;
    over_warning: boolean;
    over_limit: boolean;
  }

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

  Prefix registration logic that adds 'metrx_' namespace to all tools. Wraps the original server.registerTool to apply rate limiting and automatically prefix tool names (e.g., 'get_budget_status' becomes 'metrx_get_budget_status').

  // ── 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);
  };

• src/services/formatters.ts:149-172 (helper)

  formatBudgetStatus helper function that formats the BudgetStatus API response into a human-readable markdown string with total budgets, warnings, exceeded counts, and detailed budget information.

  /** Format budget status */
  export function formatBudgetStatus(status: BudgetStatus): string {
    if (!status.has_budgets) {
      return 'No budgets configured. Use set_budget to create spending limits for your agents.';
    }
  
    const lines: string[] = [
      `## Budget Status`,
      '',
      `**Total Budgets**: ${status.total_budgets}`,
      `**Warnings**: ${status.warning_count}`,
      `**Exceeded**: ${status.exceeded_count}`,
      `**Paused**: ${status.paused_count}`,
    ];
  
    if (status.budgets.length > 0) {
      lines.push('');
      for (const b of status.budgets) {
        lines.push(formatBudget(b));
      }
    }
  
    return lines.join('\n');
  }