don-aie-cohort8/langsmith-mcp-server

LangSmith MCP Server

FastMCP-based MCP server exposing LangSmith read-only tools for querying existing traces (runs, children, URLs) without extra instrumentation.

Tools

• ls_list_runs(project_name, is_root=True, limit=50, select?) — List recent runs with filtering
• ls_read_run(run_id, hydrate_children=False, child_limit=100) — Read single run with optional children
• ls_get_run_url(run_id) — Generate shareable LangSmith URLs
• ls_list_children(parent_run_id, limit=100) — List child spans for parent run

Requirements

• Python 3.10+
• LANGSMITH_API_KEY in your environment
• Optional: LANGSMITH_ENDPOINT for on-prem deployments

Quick Start

# Clone and setup
git clone <repo-url>
cd langsmith-mcp-server

# Install dependencies (uv manages environment automatically)
uv sync
export LANGSMITH_API_KEY="lsv2_pt_..."

# Run smoke test
uv run python tests/smoke_test.py

# Run unit tests
uv run pytest tests/test_server.py -v

Run as MCP Server

Local Development

Recommended (using fastmcp.json for configuration):

# FastMCP auto-detects fastmcp.json in current directory
fastmcp run

# Or via uv
uv run fastmcp run fastmcp.json

Alternative (direct Python):

uv run python src/server.py

FastMCP Cloud Deployment

Deploy to FastMCP Cloud for free hosting:

1. Push to GitHub: don-aie-cohort8/langsmith-mcp-server
2. Sign in to https://fastmcp.cloud
3. Create new project:
   • Repository: don-aie-cohort8/langsmith-mcp-server
   • Branch: main
   • Entrypoint: src/server.py:app
4. Add environment variable: LANGSMITH_API_KEY
5. Deploy!

Auto-deploys on every push to main.

MCP Client Configuration

Local Development

Add to your MCP client config (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "langsmith-local": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/langsmith-mcp-server/src/server.py:app"
      ]
    }
  }
}

Note: Replace /absolute/path/to/langsmith-mcp-server with your actual project path.

Why this pattern?

• Uses uv run --with fastmcp per official FastMCP recommendations
• Creates isolated environment with clean dependency management
• Avoids dependency on global fastmcp installation
• Runtime dependencies pulled from pyproject.toml via editable install
• No need to list all dependencies in MCP config

FastMCP Cloud

For cloud deployment:

{
  "mcpServers": {
    "langsmith-cloud": {
      "url": "https://langsmith-mcp-server.fastmcp.app/mcp"
    }
  }
}

Project Structure

Following FastMCP and Python best practices:

langsmith-mcp-server/
├── src/
│   └── server.py               # MCP server implementation (~190 lines)
├── tests/
│   ├── smoke_test.py           # Startup validation
│   ├── test_server.py          # Unit tests
│   ├── test_integration.py     # Integration tests
│   └── README.md               # Testing documentation
├── scripts/
│   ├── integration_demo.py     # Demo script for testing tools
│   └── claude-agent-sdk-testing/  # Claude Agent SDK integration
├── docs/
│   ├── PRODUCTION_READINESS.md # Production deployment guide
│   ├── MCP_FIX_REPORT.md       # Historical fix documentation
│   ├── SERIALIZATION_FIX.md    # Pydantic compatibility fixes
│   └── TESTING_REPORT.md       # Testing results
├── notebooks/                  # Jupyter notebooks for exploration
├── fastmcp.json                # Deployment configuration
├── pyproject.toml              # Package metadata and dependencies
└── README.md                   # This file

Dependency Management

This project uses a dual-file approach for dependencies:

• pyproject.toml: Defines all Python dependencies (runtime + dev)
• fastmcp.json: Deployment configuration that references pyproject.toml via "editable": ["."]

When you run uv sync, dependencies are installed from pyproject.toml. FastMCP automatically loads them via the editable install.

Usage Tips

• Use select=["id","name","error","extra"] for minimal payloads
• LangGraph auto-instrumented config appears under run.extra (e.g., graph_id, thread_id, research_model)
• All tools are read-only by design (no create/update/delete operations)

References

Client:

• FastMCP Client Overview
• FastMCP Client Transports

Server:

• FastMCP Testing Best Practices
• FastMCP Server Configuration
• FastMCP Cloud Deployment