LangSmith MCP Server

Fetch LangSmith runs (traces, tools, chains, etc.) from one or more projects using flexible filters, query language expressions, and trace-level constraints.

🧩 PURPOSE

This is a general-purpose LangSmith run fetcher designed for analytics, trace export, and automated exploration.

It wraps client.list_runs() with complete support for:

• Multiple project names or IDs

• The Filter Query Language (FQL) for precise queries

• Hierarchical filtering across trace trees

• Sorting and result limiting

It returns raw suitable for further analysis or export.

⚙️ PARAMETERS

project_name : str The project name to fetch runs from. For multiple projects, use JSON array string (e.g., '["project1", "project2"]').

trace_id : str, optional Return only runs that belong to a specific trace tree. It is a UUID string, e.g. "123e4567-e89b-12d3-a456-426614174000".

run_type : str, optional Filter runs by type (e.g. "llm", "chain", "tool", "retriever").

error : str, optional Filter by error status: "true" for errored runs, "false" for successful runs.

is_root : str, optional Filter root traces: "true" for only top-level traces, "false" to exclude roots. If not provided, returns all runs.

filter : str, optional A Filter Query Language (FQL) expression that filters runs by fields, metadata, tags, feedback, latency, or time.

trace_filter : str, optional Filter applied to the root run in each trace tree. Lets you select child runs based on root attributes or feedback.

tree_filter : str, optional Filter applied to any run in the trace tree (including siblings or children). Example: python 'eq(name,"ExpandQuery")' → return runs if any run in their trace had that name.

order_by : str, default "-start_time" Sort field; prefix with "-" for descending order.

limit : int, default 50 Maximum number of runs to return.

reference_example_id : str, optional Filter runs by reference example ID. Returns only runs associated with the specified dataset example ID.

format_type : str, default "pretty" Output format for extracted messages. Options: - "pretty" (default): Human-readable formatted text focusing on human/AI/tool message exchanges - "json": Pretty-printed JSON format - "raw": Compact single-line JSON format

📤 RETURNS

Dict[str, Any] Dictionary containing: - If format_type is set: {"formatted": str} - formatted string representation of messages - If format_type is not set: {"runs": List[Dict]} - list of LangSmith run dictionaries

🧪 EXAMPLES

1️⃣ Get latest 10 root runs

2️⃣ Get all tool runs that errored

3️⃣ Get all runs that took >5s and have tag "experimental"

4️⃣ Get all runs in a specific conversation thread

5️⃣ List all runs called "extractor" whose root trace has feedback user_score=1

6️⃣ List all runs that started after a timestamp and either errored or got low feedback

7️⃣ Get formatted messages for conversational AI (default: pretty format)

8️⃣ Get messages in JSON format

🧠 NOTES FOR AGENTS

• Use this to query LangSmith data sources dynamically.

• Compose FQL strings programmatically based on your intent.

• Combine filter, trace_filter, and tree_filter for hierarchical logic.

• Always verify that project_name matches an existing LangSmith project.

• Returned dict objects have fields like:

• id, name, run_type, inputs, outputs, error, start_time, end_time, latency, metadata, feedback, etc.

• If the trace is big, save it to a file (if you have this ability) and analyze it locally.

• For conversational AI agents: Use format_type="pretty" (default) to get human-readable message exchanges focusing on human/AI/tool messages rather than full trace details.