Metrx MCP Server

Instructions

Implementation Reference

• src/tools/optimization.ts:16-85 (handler)

  The tool handler implementation that executes get_optimization_recommendations. Calls the API client to fetch optimization data for either a specific agent or fleet-wide, processes the results, and returns formatted recommendations. The handler is registered here as 'get_optimization_recommendations' and gets prefixed with 'metrx_' in the main server setup.

  server.registerTool(
    'get_optimization_recommendations',
    {
      title: 'Get Optimization Recommendations',
      description:
        'Get AI-powered cost optimization recommendations for a specific agent or your entire fleet. ' +
        'Returns actionable suggestions including model switching, token guardrails, provider arbitrage, ' +
        'batch processing opportunities, and revenue intelligence insights. ' +
        'Each suggestion includes estimated monthly savings and confidence level. ' +
        'Do NOT use for implementing fixes — use apply_optimization for one-click fixes or create_model_experiment to validate first.',
      inputSchema: {
        agent_id: z
          .string()
          .uuid()
          .optional()
          .describe('Specific agent to analyze. Omit for fleet-wide recommendations.'),
        include_revenue: z
          .boolean()
          .default(true)
          .describe('Include revenue-side insights (R3, R4, R6) in addition to cost optimizations'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ agent_id, include_revenue }) => {
      const path = agent_id ? `/agents/${agent_id}/metrics` : '/dashboard';
  
      const params: Record<string, string | boolean> = {
        include_optimization: true,
      };
      if (include_revenue !== undefined) {
        params.include_revenue = include_revenue;
      }
  
      const result = await client.get<{
        optimization?: OptimizationResult;
      }>(path, params as Record<string, string>);
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error fetching recommendations: ${result.error}` }],
          isError: true,
        };
      }
  
      const optimization = result.data?.optimization;
      if (!optimization || optimization.suggestion_count === 0) {
        return {
          content: [
            {
              type: 'text',
              text: agent_id
                ? `No optimization recommendations for this agent. The agent may be already well-optimized or may not have enough data yet.`
                : `No fleet-wide optimization recommendations. Your agents are running efficiently.`,
            },
          ],
        };
      }
  
      const text = formatOptimizations(optimization);
  
      return {
        content: [{ type: 'text', text }],
      };
    }
  );

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

  The tool registration wrapper that prefixes all tools with 'metrx_'. This wrapper intercepts tool registration calls and adds the 'metrx_' prefix to avoid namespace collisions when multiple MCP servers are used together. It also wraps handlers with rate limiting logic.

  // ── 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/types.ts:123-152 (schema)

  Type definitions for the tool's input/output. OptimizationSuggestion defines individual recommendations with type, title, description, impact, confidence, and implementation details. OptimizationResult is the aggregate response containing all suggestions, total savings, revenue impact, suggestion count, and analysis confidence metrics.

  export interface OptimizationSuggestion {
    type: string;
    title: string;
    description: string;
    impact_monthly_cents: number;
    confidence: string;
    savings_pct?: number;
    caveat?: string;
    action_label?: string;
    is_revenue?: boolean;
    implementation?: {
      one_click: boolean;
      endpoint?: string;
      payload?: Record<string, unknown>;
    };
  }
  
  export interface OptimizationResult {
    suggestions: OptimizationSuggestion[];
    total_monthly_savings_cents: number;
    total_revenue_impact_cents?: number;
    suggestion_count: number;
    computed_at: string;
    analysis_confidence?: {
      cost_confidence: number;
      quality_confidence: number;
      display_confidence: number;
      confidence_tier: string;
    };
  }

• src/services/formatters.ts:81-147 (helper)

  Helper function that formats the OptimizationResult into human-readable text for MCP tool responses. Separates cost and revenue suggestions, displays total savings, revenue impact, confidence levels, and formats each suggestion with its impact, description, caveats, and one-click availability.

  export function formatOptimizations(result: OptimizationResult): string {
    const lines: string[] = [
      `## Optimization Recommendations`,
      '',
      `**Total Potential Savings**: ${formatCents(result.total_monthly_savings_cents)}/month`,
      `**Suggestions**: ${result.suggestion_count}`,
    ];
  
    if (result.total_revenue_impact_cents) {
      lines.push(`**Revenue Impact**: ${formatCents(result.total_revenue_impact_cents)}/month`);
    }
  
    if (result.analysis_confidence) {
      lines.push(
        `**Confidence**: ${result.analysis_confidence.confidence_tier} (${formatPct(
          result.analysis_confidence.display_confidence
        )})`
      );
    }
  
    if (result.suggestions.length > 0) {
      lines.push('');
  
      // Separate cost and revenue suggestions
      const costSuggestions = result.suggestions.filter((s) => !s.is_revenue);
      const revenueSuggestions = result.suggestions.filter((s) => s.is_revenue);
  
      if (costSuggestions.length > 0) {
        lines.push('### Cost Optimization');
        for (const s of costSuggestions) {
          lines.push(formatSuggestion(s));
        }
      }
  
      if (revenueSuggestions.length > 0) {
        lines.push('');
        lines.push('### Revenue Intelligence');
        for (const s of revenueSuggestions) {
          lines.push(formatSuggestion(s));
        }
      }
    }
  
    return lines.join('\n');
  }
  
  function formatSuggestion(s: OptimizationSuggestion): string {
    const impact = s.is_revenue
      ? `+${formatCents(s.impact_monthly_cents)}/mo revenue`
      : `${formatCents(s.impact_monthly_cents)}/mo savings`;
  
    const parts = [
      `\n**${s.title}** (${s.confidence} confidence)`,
      `Impact: ${impact}${s.savings_pct ? ` (${s.savings_pct}%)` : ''}`,
      s.description,
    ];
  
    if (s.caveat) {
      parts.push(`⚠️ ${s.caveat}`);
    }
  
    if (s.implementation?.one_click) {
      parts.push(`✅ One-click apply available`);
    }
  
    return parts.join('\n');
  }