Add list-spans and get-span-by-id tools

[mecampbellsoup]

Summary

The MCP server exposes tools for projects, traces, and stats, but has no tools for reading span-level data. This forces users to fall back to raw REST API calls (/api/v1/private/spans) for the most common debugging workflow: inspecting individual LLM calls, tool invocations, per-span timing, and token usage within a trace.

(Transferred from comet-ml/opik#6077)

Current state

The MCP server provides:

• list-projects
• list-traces / get-trace-by-id
• get-trace-stats / get-trace-threads

get-trace-by-id returns spanCount and llmSpanCount but does not include the actual span data, and there's no flag to expand it.

Requested tools

1. list-spans — List spans for a given trace ID (with pagination). Equivalent to GET /api/v1/private/spans?trace_id={id}.
2. get-span-by-id — Get full details for a single span. Equivalent to GET /api/v1/private/spans/{id}.

Alternatively, an include_spans flag on get-trace-by-id that embeds child spans in the response would also work.

Use case

When debugging LLM application behavior via an AI coding assistant (Claude Code, Cursor, etc.), the primary workflow is:

1. Find the trace for a request (list-traces ✅)
2. Drill into spans to see what the LLM did — which tools it called, how long each step took, token usage per span (no MCP tool — forced to curl)

Span inspection is arguably the most valuable debugging action, and it's the one thing the MCP can't do.

Environment

• opik-mcp v2.0.0 via npx -y opik-mcp
• Connected to Comet cloud (comet.com)
• Using Claude Code with MCP integration