List traces

Instructions

Implementation Reference

• src/tools.ts:14-32 (registration)

  Registration of the 'listTraces' tool via server.registerTool with its name, metadata, inputSchema, and handler.

  server.registerTool(
    "listTraces",
    {
      title: "List traces",
      description:
        "List Langfuse traces with filters. Returns summary metadata (use getTrace for the full observation tree).",
      inputSchema: {
        ...paginationShape,
        ...timeRangeShape,
        userId: z.string().optional(),
        sessionId: z.string().optional(),
        name: z.string().optional().describe("Exact trace name match"),
        environment: z.string().optional(),
        tags: z.array(z.string()).optional(),
        orderBy: z.string().optional().describe("e.g. 'timestamp.desc' (default)"),
      },
    },
    async (args) => asJson(await client.get("/api/public/traces", args)),
  );

• src/tools.ts:31-31 (handler)

  The handler function that executes the listTraces tool logic: calls client.get('/api/public/traces', args) and wraps the result in JSON content.

  async (args) => asJson(await client.get("/api/public/traces", args)),

• src/tools.ts:20-29 (schema)

  Input schema for listTraces, using paginationShape, timeRangeShape, and optional filters (userId, sessionId, name, environment, tags, orderBy).

  inputSchema: {
    ...paginationShape,
    ...timeRangeShape,
    userId: z.string().optional(),
    sessionId: z.string().optional(),
    name: z.string().optional().describe("Exact trace name match"),
    environment: z.string().optional(),
    tags: z.array(z.string()).optional(),
    orderBy: z.string().optional().describe("e.g. 'timestamp.desc' (default)"),
  },

• src/tools.ts:3-12 (helper)

  Imported shared schema shapes used by listTraces: paginationShape (page, limit) and timeRangeShape (fromTimestamp, toTimestamp).

  import type { LangfuseClient } from "./client.js";
  import { paginationShape, timeRangeShape } from "./schemas.js";
  
  const asJson = (data: unknown) => ({
    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
  });
  
  const enc = encodeURIComponent;
  
  export function registerTools(server: McpServer, client: LangfuseClient): void {

• src/schemas.ts:3-17 (helper)

  Definition of paginationShape and timeRangeShape used as input schema building blocks for listTraces.

  export const paginationShape = {
    page: z.number().int().positive().optional().describe("Page number (default 1)"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Items per page (default 50, max 100)"),
  };
  
  export const timeRangeShape = {
    fromTimestamp: z.string().datetime().optional().describe("ISO 8601 lower bound (inclusive)"),
    toTimestamp: z.string().datetime().optional().describe("ISO 8601 upper bound (exclusive)"),
  };