# 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

```bash
# 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):
```bash
# FastMCP auto-detects fastmcp.json in current directory
fastmcp run

# Or via uv
uv run fastmcp run fastmcp.json
```

**Alternative** (direct Python):
```bash
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.):

```json
{
  "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:

```json
{
  "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](https://gofastmcp.com/clients/client)
- [FastMCP Client Transports](https://gofastmcp.com/clients/transports)

**Server:**

- [FastMCP Testing Best Practices](https://gofastmcp.com/development/tests)
- [FastMCP Server Configuration](https://gofastmcp.com/deployment/server-configuration)
- [FastMCP Cloud Deployment](https://fastmcp.cloud)