Metrx MCP Server

Instructions

Implementation Reference

• src/tools/dashboard.ts:64-124 (handler)

  Main implementation of the list_agents tool. Registers the tool with name 'list_agents' (auto-prefixed to 'metrx_list_agents' by the server middleware), defines the input schema with optional status and category filters, and implements the handler logic that calls the /agents API endpoint and formats the results as a readable list of agents with their IDs, names, status, category, monthly costs, and ROI multipliers.

  server.registerTool(
    'list_agents',
    {
      title: 'List Agents',
      description:
        'List all AI agents in your organization with their status, category, and cost. ' +
        'Optionally filter by status or category. Returns agent IDs needed for other tools. ' +
        'Do NOT use for detailed per-agent analysis — use get_agent_detail for that.',
      inputSchema: {
        status: z
          .enum(['active', 'idle', 'error', 'archived'])
          .optional()
          .describe('Filter by agent status'),
        category: z
          .string()
          .optional()
          .describe('Filter by agent category (e.g., "sales", "support", "engineering")'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ status, category }) => {
      const params: Record<string, string> = {};
      if (status) params.status = status;
      if (category) params.category = category;
  
      const result = await client.get<{ agents: AgentDetail[] }>('/agents', params);
  
      if (result.error) {
        return {
          content: [{ type: 'text', text: `Error listing agents: ${result.error}` }],
          isError: true,
        };
      }
  
      const agents = result.data?.agents || [];
      if (agents.length === 0) {
        return {
          content: [{ type: 'text', text: 'No agents found matching the specified filters.' }],
        };
      }
  
      const lines: string[] = [`## Agents (${agents.length})`, ''];
      for (const agent of agents) {
        const cost = agent.monthly_cost_cents ? formatCents(agent.monthly_cost_cents) : 'N/A';
        const roi = agent.roi_multiplier ? ` | ${agent.roi_multiplier.toFixed(1)}x ROI` : '';
        lines.push(
          `- **${agent.name}** [${agent.agent_key}] — ${agent.status} | ${agent.category} | ${cost}/mo${roi}`
        );
        lines.push(`  ID: ${agent.id}`);
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    }
  );

• src/tools/dashboard.ts:72-81 (schema)

  Input schema definition for list_agents tool using zod validation. Defines optional 'status' parameter (enum: active, idle, error, archived) and 'category' parameter (string) for filtering the agent list.

  inputSchema: {
    status: z
      .enum(['active', 'idle', 'error', 'archived'])
      .optional()
      .describe('Filter by agent status'),
    category: z
      .string()
      .optional()
      .describe('Filter by agent category (e.g., "sales", "support", "engineering")'),
  },

• src/types.ts:30-40 (schema)

  AgentDetail interface type definition used for the list_agents tool response. Extends AgentSummary with additional fields like description, framework_source, outcome_rung, primary_model, failure_risk_score, secondary_categories, and created_at.

  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/tools/dashboard.ts:14-14 (registration)

  The registerDashboardTools function exports the registration logic that is called from src/index.ts line 106. This function registers all dashboard-related tools including list_agents with the MCP server.

  export function registerDashboardTools(server: McpServer, client: MetrxApiClient): void {

• src/services/formatters.ts:21-23 (helper)

  The formatCents helper function used by list_agents handler to convert monthly_cost_cents values to dollar string format for display in the agent list output.

  export function formatCents(cents: number): string {
    return `$${(cents / 100).toFixed(2)}`;
  }