Metrx MCP Server

Instructions

Implementation Reference

• src/tools/optimization.ts:266-335 (handler)

  The compare_models tool handler function that executes the model comparison logic. It accepts optional parameters (current_model, tier, provider), makes an API call to /agents/models/compare, and formats the response as a markdown table showing model pricing, capabilities, and savings estimates.

  async ({ current_model, tier, provider }) => {
    // This tool can work purely client-side using model-data,
    // but we route through the API for consistency
    const params: Record<string, string> = {};
    if (current_model) params.current_model = current_model;
    if (tier) params.tier = tier;
    if (provider) params.provider = provider;
  
    const result = await client.get<{
      models: Array<{
        model: string;
        provider: string;
        tier: string;
        input_cost_per_1m: number;
        output_cost_per_1m: number;
        context_window: number;
        supports_batch: boolean;
        supports_caching: boolean;
        savings_vs_current_pct?: number;
      }>;
      current_model_info?: {
        model: string;
        provider: string;
        input_cost_per_1m: number;
        output_cost_per_1m: number;
      };
    }>('/agents/models/compare', params);
  
    if (result.error) {
      return {
        content: [{ type: 'text', text: `Error comparing models: ${result.error}` }],
        isError: true,
      };
    }
  
    const data = result.data!;
    const lines: string[] = ['## Model Comparison', ''];
  
    if (data.current_model_info) {
      const c = data.current_model_info;
      lines.push(
        `**Current**: ${c.model} (${c.provider}) — $${c.input_cost_per_1m}/M in, $${c.output_cost_per_1m}/M out`
      );
      lines.push('');
    }
  
    lines.push('### Alternatives');
    lines.push(
      '| Model | Provider | Tier | Input $/M | Output $/M | Context | Batch | Cache | Savings |'
    );
    lines.push(
      '|-------|----------|------|-----------|------------|---------|-------|-------|---------|'
    );
  
    for (const m of data.models) {
      const savings =
        m.savings_vs_current_pct !== undefined ? `${m.savings_vs_current_pct}%` : '—';
      lines.push(
        `| ${m.model} | ${m.provider} | ${m.tier} | $${m.input_cost_per_1m} | $${
          m.output_cost_per_1m
        } | ${(m.context_window / 1000).toFixed(0)}K | ${m.supports_batch ? '✓' : '✗'} | ${
          m.supports_caching ? '✓' : '✗'
        } | ${savings} |`
      );
    }
  
    return {
      content: [{ type: 'text', text: lines.join('\n') }],
    };
  }

• src/tools/optimization.ts:233-336 (registration)

  Tool registration using server.registerTool() with name 'compare_models'. Includes the tool's title, description explaining it compares LLM model pricing and capabilities across providers, and the complete tool configuration including annotations.

  server.registerTool(
    'compare_models',
    {
      title: 'Compare Models',
      description:
        'Compare LLM model pricing and capabilities across providers. ' +
        'Returns pricing per 1M tokens, context window sizes, batch/cache support, ' +
        'and cost savings estimates for switching from a current model to alternatives. ' +
        'Works without any usage data (Day 0 value). ' +
        'Do NOT use for agent-specific recommendations — use get_optimization_recommendations which factors in actual usage patterns.',
      inputSchema: {
        current_model: z
          .string()
          .optional()
          .describe(
            'Current model to compare against (e.g., "gpt-4o", "claude-sonnet-4-20250514")'
          ),
        tier: z
          .enum(['frontier', 'balanced', 'efficient', 'budget'])
          .optional()
          .describe('Capability tier to filter alternatives'),
        provider: z
          .string()
          .optional()
          .describe('Filter to a specific provider (e.g., "openai", "anthropic", "google")'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ current_model, tier, provider }) => {
      // This tool can work purely client-side using model-data,
      // but we route through the API for consistency
      const params: Record<string, string> = {};
      if (current_model) params.current_model = current_model;
      if (tier) params.tier = tier;
      if (provider) params.provider = provider;
  
      const result = await client.get<{
        models: Array<{
          model: string;
          provider: string;
          tier: string;
          input_cost_per_1m: number;
          output_cost_per_1m: number;
          context_window: number;
          supports_batch: boolean;
          supports_caching: boolean;
          savings_vs_current_pct?: number;
        }>;
        current_model_info?: {
          model: string;
          provider: string;
          input_cost_per_1m: number;
          output_cost_per_1m: number;
        };
      }>('/agents/models/compare', params);
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error comparing models: ${result.error}` }],
          isError: true,
        };
      }
  
      const data = result.data!;
      const lines: string[] = ['## Model Comparison', ''];
  
      if (data.current_model_info) {
        const c = data.current_model_info;
        lines.push(
          `**Current**: ${c.model} (${c.provider}) — $${c.input_cost_per_1m}/M in, $${c.output_cost_per_1m}/M out`
        );
        lines.push('');
      }
  
      lines.push('### Alternatives');
      lines.push(
        '| Model | Provider | Tier | Input $/M | Output $/M | Context | Batch | Cache | Savings |'
      );
      lines.push(
        '|-------|----------|------|-----------|------------|---------|-------|-------|---------|'
      );
  
      for (const m of data.models) {
        const savings =
          m.savings_vs_current_pct !== undefined ? `${m.savings_vs_current_pct}%` : '—';
        lines.push(
          `| ${m.model} | ${m.provider} | ${m.tier} | $${m.input_cost_per_1m} | $${
            m.output_cost_per_1m
          } | ${(m.context_window / 1000).toFixed(0)}K | ${m.supports_batch ? '✓' : '✗'} | ${
            m.supports_caching ? '✓' : '✗'
          } | ${savings} |`
        );
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    }
  );

• src/tools/optimization.ts:243-258 (schema)

  Input schema definition using Zod validation for the compare_models tool. Defines three optional parameters: current_model (string), tier (enum: 'frontier', 'balanced', 'efficient', 'budget'), and provider (string), each with appropriate descriptions.

  inputSchema: {
    current_model: z
      .string()
      .optional()
      .describe(
        'Current model to compare against (e.g., "gpt-4o", "claude-sonnet-4-20250514")'
      ),
    tier: z
      .enum(['frontier', 'balanced', 'efficient', 'budget'])
      .optional()
      .describe('Capability tier to filter alternatives'),
    provider: z
      .string()
      .optional()
      .describe('Filter to a specific provider (e.g., "openai", "anthropic", "google")'),
  },

• src/tools/model-pricing.ts:14-29 (schema)

  Type definitions for model pricing data including ModelProvider, ModelTier enums, and ModelPricingEntry interface that defines the structure of model pricing information used by compare_models.

  export type ModelProvider = 'openai' | 'anthropic' | 'google' | 'mistral' | 'cohere';
  export type ModelTier = 'frontier' | 'balanced' | 'efficient' | 'budget';
  
  export interface ModelPricingEntry {
    model: string;
    provider: ModelProvider;
    tier: ModelTier;
    /** USD per 1M input tokens */
    input_cost_per_1m: number;
    /** USD per 1M output tokens (0 for embedding-only models) */
    output_cost_per_1m: number;
    /** Maximum context window in tokens */
    context_window: number;
    supports_batch: boolean;
    supports_caching: boolean;
  }

• src/tools/model-pricing.ts:274-302 (helper)

  Helper functions that support the compare_models tool: getModelPricing() for resolving model name aliases, getModelsByProvider() and getModelsByTier() for filtering models, and getCoveredProviders() for listing available providers.

  export function getModelPricing(modelName: string): ModelPricingEntry | undefined {
    const canonical = MODEL_ALIASES[modelName] ?? modelName;
    return MODEL_PRICING[canonical];
  }
  
  /**
   * Get all models for a given provider, sorted by input cost descending.
   */
  export function getModelsByProvider(provider: ModelProvider): ModelPricingEntry[] {
    return Object.values(MODEL_PRICING)
      .filter((m) => m.provider === provider)
      .sort((a, b) => b.input_cost_per_1m - a.input_cost_per_1m);
  }
  
  /**
   * Get all models for a given tier, sorted by input cost ascending.
   */
  export function getModelsByTier(tier: ModelTier): ModelPricingEntry[] {
    return Object.values(MODEL_PRICING)
      .filter((m) => m.tier === tier)
      .sort((a, b) => a.input_cost_per_1m - b.input_cost_per_1m);
  }
  
  /**
   * Get the list of all providers with at least one model entry.
   */
  export function getCoveredProviders(): ModelProvider[] {
    return [...new Set(Object.values(MODEL_PRICING).map((m) => m.provider))].sort() as ModelProvider[];
  }