Metrx MCP Server

Instructions

Implementation Reference

• src/tools/dashboard.ts:126-161 (handler)

  The main handler implementation for get_agent_detail tool. It validates the agent_id UUID parameter, makes a GET request to /agents/{agent_id}, handles errors, and formats the response using formatAgentDetail.

  // ── get_agent_detail ──
  server.registerTool(
    'get_agent_detail',
    {
      title: 'Get Agent Detail',
      description:
        'Get detailed information about a specific agent including its model, ' +
        'framework, category, outcome configuration, and failure risk score. ' +
        'Do NOT use for fleet-wide overviews — use get_cost_summary instead.',
      inputSchema: {
        agent_id: z.string().uuid().describe('The agent UUID to look up'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ agent_id }) => {
      const result = await client.get<AgentDetail>(`/agents/${agent_id}`);
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error fetching agent: ${result.error}` }],
          isError: true,
        };
      }
  
      const text = formatAgentDetail(result.data!);
  
      return {
        content: [{ type: 'text', text }],
      };
    }
  );

• src/tools/dashboard.ts:127-144 (schema)

  Tool registration with input schema definition - validates agent_id as a required UUID string. Includes tool metadata like title, description, and annotations.

  server.registerTool(
    'get_agent_detail',
    {
      title: 'Get Agent Detail',
      description:
        'Get detailed information about a specific agent including its model, ' +
        'framework, category, outcome configuration, and failure risk score. ' +
        'Do NOT use for fleet-wide overviews — use get_cost_summary instead.',
      inputSchema: {
        agent_id: z.string().uuid().describe('The agent UUID to look up'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },

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

  The registration wrapper that adds the 'metrx_' prefix to all tools. The tool registered as 'get_agent_detail' becomes 'metrx_get_agent_detail'. Also wraps handlers with rate limiting.

  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:30-40 (schema)

  Type definition for AgentDetail interface - extends AgentSummary with additional fields like description, framework_source, primary_model, failure_risk_score, etc.

  export interface AgentDetail extends AgentSummary {
    description?: string;
    parent_agent_id?: string;
    framework_source?: string;
    outcome_value_cents?: number;
    outcome_rung?: string;
    primary_model?: string;
    failure_risk_score?: number;
    secondary_categories?: string[];
    created_at: string;
  }

• src/services/formatters.ts:190-224 (helper)

  formatAgentDetail helper function that formats the AgentDetail object into a human-readable markdown string with sections for key, category, status, model, framework, risk score, etc.

  export function formatAgentDetail(agent: AgentDetail): string {
    const lines: string[] = [
      `## Agent: ${agent.name}`,
      '',
      `**Key**: ${agent.agent_key}`,
      `**Category**: ${agent.category}`,
      `**Status**: ${agent.status}`,
      `**Background**: ${agent.is_background ? 'Yes' : 'No'}`,
    ];
  
    if (agent.primary_model) {
      lines.push(`**Primary Model**: ${agent.primary_model}`);
    }
    if (agent.framework_source) {
      lines.push(`**Framework**: ${agent.framework_source}`);
    }
    if (agent.outcome_rung) {
      lines.push(`**Outcome Rung**: ${agent.outcome_rung}`);
    }
    if (agent.failure_risk_score !== undefined && agent.failure_risk_score > 0) {
      lines.push(
        `**Failure Risk**: ${formatPct(agent.failure_risk_score)} ${
          agent.failure_risk_score > 0.7 ? '🔴' : agent.failure_risk_score > 0.3 ? '🟡' : '🟢'
        }`
      );
    }
    if (agent.secondary_categories && agent.secondary_categories.length > 0) {
      lines.push(`**Secondary Categories**: ${agent.secondary_categories.join(', ')}`);
    }
    if (agent.last_call_at) {
      lines.push(`**Last Active**: ${agent.last_call_at}`);
    }
  
    return lines.join('\n');
  }