Langfuse MCP Server

Instructions

Implementation Reference

• src/tools/top-expensive-traces.ts:12-67 (handler)

  Main handler function that implements the tool logic: queries Langfuse API for traces ordered by cost, filters and formats the top expensive ones.

  export async function topExpensiveTraces(
    client: LangfuseAnalyticsClient,
    args: z.infer<typeof topExpensiveTracesSchema>
  ) {
    const tags = args.environment ? [`environment:${args.environment}`] : undefined;
  
    const response = await client.listTraces({
      fromTimestamp: args.from,
      toTimestamp: args.to,
      orderBy: 'totalCost',
      orderDirection: 'desc', // Most expensive first
      limit: args.limit,
      tags,
    });
  
    const traces: ExpensiveTrace[] = [];
  
    // Parse the response data - correct structure based on Langfuse API
    if (response.data && Array.isArray(response.data)) {
      response.data
        .filter((trace: any) => (trace.totalCost || 0) > 0) // Only include traces with cost
        .sort((a: any, b: any) => (b.totalCost || 0) - (a.totalCost || 0)) // Sort by cost descending
        .slice(0, args.limit) // Limit results
        .forEach((trace: any) => {
          traces.push({
            traceId: trace.id,
            name: trace.name || 'Unnamed trace',
            totalCost: trace.totalCost || 0,
            totalTokens: trace.totalTokens || 0,
            timestamp: trace.timestamp || trace.startTime,
            userId: trace.userId,
            tags: trace.tags || [],
            metadata: trace.metadata,
          });
        });
    }
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(
            {
              projectId: client.getProjectId(),
              from: args.from,
              to: args.to,
              environment: args.environment,
              traces,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/top-expensive-traces.ts:5-10 (schema)

  Zod schema defining the input parameters for the tool.

  export const topExpensiveTracesSchema = z.object({
    from: z.string().datetime(),
    to: z.string().datetime(),
    limit: z.number().optional().default(10),
    environment: z.string().optional(),
  });

• src/index.ts:1020-1023 (registration)

  Dispatch case in the MCP callToolRequest handler that validates input with schema and invokes the handler function.

  case 'top_expensive_traces': {
    const args = topExpensiveTracesSchema.parse(request.params.arguments);
    return await topExpensiveTraces(this.client, args);
  }

• src/index.ts:245-273 (registration)

  Tool metadata and input schema exposed in the MCP listToolsRequest handler.

  {
    name: 'top_expensive_traces',
    description:
      'Find the most expensive traces by cost over a time period.',
    inputSchema: {
      type: 'object',
      properties: {
        from: {
          type: 'string',
          format: 'date-time',
          description: 'Start timestamp (ISO 8601)',
        },
        to: {
          type: 'string',
          format: 'date-time',
          description: 'End timestamp (ISO 8601)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of traces to return (default: 10)',
        },
        environment: {
          type: 'string',
          description: 'Optional environment filter',
        },
      },
      required: ['from', 'to'],
    },
  },

• src/index.ts:56-56 (registration)

  Import of the handler function and schema into the main server file.

  import { topExpensiveTraces, topExpensiveTracesSchema } from './tools/top-expensive-traces.js';