Langfuse MCP Server

Instructions

Implementation Reference

• src/tools/get-trace-detail.ts:9-70 (handler)

  The core handler function that fetches a specific trace by ID, retrieves associated observations, constructs a detailed TraceDetail object, and returns it as formatted JSON. Handles errors by returning error content.

  export async function getTraceDetail(
    client: LangfuseAnalyticsClient,
    args: z.infer<typeof getTraceDetailSchema>
  ) {
    try {
      const [traceResponse, observationsResponse] = await Promise.all([
        client.getTrace(args.traceId),
        client.listObservations({ traceId: args.traceId }),
      ]);
  
      const trace = traceResponse;
      const observations = observationsResponse.data || [];
  
      const detail: TraceDetail = {
        traceId: trace.id,
        name: trace.name || 'Unnamed trace',
        totalCost: trace.totalCost || 0,
        totalTokens: trace.totalTokens || 0,
        timestamp: trace.timestamp,
        userId: trace.userId,
        tags: trace.tags,
        metadata: trace.metadata,
        observations: observations.map((obs: any) => ({
          id: obs.id,
          type: obs.type,
          name: obs.name,
          startTime: obs.startTime,
          endTime: obs.endTime,
          model: obs.model,
          inputTokens: obs.usage?.input,
          outputTokens: obs.usage?.output,
          totalTokens: obs.usage?.total,
          cost: obs.calculatedTotalCost,
        })),
      };
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(detail, null, 2),
          },
        ],
      };
    } catch (error) {
      // Handle case where trace doesn't exist or API error
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              error: `Failed to retrieve trace ${args.traceId}: ${errorMessage}`,
              traceId: args.traceId,
            }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/get-trace-detail.ts:5-7 (schema)

  Zod schema for input validation, requiring a single 'traceId' string parameter.

  export const getTraceDetailSchema = z.object({
    traceId: z.string(),
  });

• src/index.ts:1025-1028 (registration)

  Registration in the CallToolRequest switch statement: parses arguments using the schema and invokes the handler function.

  case 'get_trace_detail': {
    const args = getTraceDetailSchema.parse(request.params.arguments);
    return await getTraceDetail(this.client, args);
  }

• src/index.ts:275-288 (registration)

  Tool metadata registration in the ListToolsRequest handler, defining name, description, and input schema for discovery.

    name: 'get_trace_detail',
    description:
      'Get detailed information about a specific trace including all observations.',
    inputSchema: {
      type: 'object',
      properties: {
        traceId: {
          type: 'string',
          description: 'The trace ID to retrieve',
        },
      },
      required: ['traceId'],
    },
  },

• src/mode-config.ts:32-32 (helper)

  Inclusion in readonly tools set, allowing the tool in readonly server mode.

  'get_trace_detail',