Metrx MCP Server

Instructions

Implementation Reference

• src/tools/optimization.ts:179-229 (handler)

  The handler function for route_model (metrx_route_model) that calls the API /agents/{agent_id}/route endpoint and formats the routing recommendation response with model comparisons, estimated savings, and confidence levels.

  async ({ agent_id, task_complexity, current_model }) => {
    const params: Record<string, string> = {
      task_complexity,
    };
    if (current_model) params.current_model = current_model;
  
    const result = await client.get<{
      recommended_model: string;
      current_model: string;
      task_complexity: string;
      estimated_savings_pct: number;
      confidence: string;
      reason: string;
    }>(`/agents/${agent_id}/route`, params);
  
    if (result.error) {
      return {
        content: [
          { type: 'text', text: `Error getting routing recommendation: ${result.error}` },
        ],
        isError: true,
      };
    }
  
    const data = result.data!;
    const lines: string[] = [
      '## Model Routing Recommendation',
      '',
      `**Task Complexity**: ${data.task_complexity}`,
      `**Current Model**: ${data.current_model}`,
      `**Recommended Model**: ${data.recommended_model}`,
      '',
    ];
  
    if (data.recommended_model !== data.current_model) {
      lines.push(
        `**Estimated Savings**: ${data.estimated_savings_pct}%`,
        `**Confidence**: ${data.confidence}`,
        '',
        `> ${data.reason}`
      );
    } else {
      lines.push(
        `> Current model is already optimal for ${data.task_complexity} complexity tasks.`
      );
    }
  
    return {
      content: [{ type: 'text', text: lines.join('\n') }],
    };
  }

• src/tools/optimization.ts:148-230 (registration)

  Tool registration for 'route_model' with title, description, input schema (agent_id, task_complexity, current_model), and annotations. This gets prefixed with 'metrx_' during server initialization.

  server.registerTool(
    'route_model',
    {
      title: 'Route Model Selection',
      description:
        'Get a model routing recommendation for a specific task based on complexity. ' +
        "Uses the agent's historical performance data and cost analysis to suggest the optimal " +
        'model for each task complexity level. Helps reduce costs by routing simple tasks ' +
        'to cheaper models while keeping complex tasks on premium models. ' +
        'Do NOT use for comparing all models at once — use compare_models for static pricing.',
      inputSchema: {
        agent_id: z.string().uuid().describe('The agent to get routing recommendations for'),
        task_complexity: z
          .enum(['low', 'medium', 'high'])
          .describe(
            'Estimated task complexity: low (simple lookups/formatting), medium (analysis/summarization), high (reasoning/generation)'
          ),
        current_model: z
          .string()
          .optional()
          .describe(
            'Currently configured model (e.g., "gpt-4o"). If omitted, uses agent primary model.'
          ),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ agent_id, task_complexity, current_model }) => {
      const params: Record<string, string> = {
        task_complexity,
      };
      if (current_model) params.current_model = current_model;
  
      const result = await client.get<{
        recommended_model: string;
        current_model: string;
        task_complexity: string;
        estimated_savings_pct: number;
        confidence: string;
        reason: string;
      }>(`/agents/${agent_id}/route`, params);
  
      if (result.error) {
        return {
          content: [
            { type: 'text', text: `Error getting routing recommendation: ${result.error}` },
          ],
          isError: true,
        };
      }
  
      const data = result.data!;
      const lines: string[] = [
        '## Model Routing Recommendation',
        '',
        `**Task Complexity**: ${data.task_complexity}`,
        `**Current Model**: ${data.current_model}`,
        `**Recommended Model**: ${data.recommended_model}`,
        '',
      ];
  
      if (data.recommended_model !== data.current_model) {
        lines.push(
          `**Estimated Savings**: ${data.estimated_savings_pct}%`,
          `**Confidence**: ${data.confidence}`,
          '',
          `> ${data.reason}`
        );
      } else {
        lines.push(
          `> Current model is already optimal for ${data.task_complexity} complexity tasks.`
        );
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    }
  );

• src/tools/optimization.ts:158-171 (schema)

  Input schema definition using zod for the route_model tool: agent_id (UUID, required), task_complexity (enum: low/medium/high, required), current_model (string, optional).

  inputSchema: {
    agent_id: z.string().uuid().describe('The agent to get routing recommendations for'),
    task_complexity: z
      .enum(['low', 'medium', 'high'])
      .describe(
        'Estimated task complexity: low (simple lookups/formatting), medium (analysis/summarization), high (reasoning/generation)'
      ),
    current_model: z
      .string()
      .optional()
      .describe(
        'Currently configured model (e.g., "gpt-4o"). If omitted, uses agent primary model.'
      ),
  },

• src/server-factory.ts:43-68 (registration)

  Registration wrapper that adds the 'metrx_' prefix to all tool names and applies rate limiting middleware. This transforms 'route_model' to 'metrx_route_model' when the tool is exposed.

  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 (primary name only — no deprecated aliases)
    const prefixedName = name.startsWith(METRX_PREFIX) ? name : `${METRX_PREFIX}${name}`;
    originalRegisterTool(prefixedName, config, wrappedHandler);
  };