Skip to content

Commit 935d6b8

Browse files
Palashioclaude
Palashio
and
claude
authored
docs(langsmith): add LangSmith MCP Server page (#2981)
Documents the LangSmith MCP Server, covering hosted and local setup, available tools, pagination, Docker deployment, environment variables, and the TypeScript community port. ## Overview <!-- Brief description of what documentation is being added/updated --> ## Type of change **Type:** [Replace with: New documentation page / Update existing documentation / Fix typo/bug/link/formatting / Remove outdated content / Other] ## Related issues/PRs <!-- Link to related issues, feature PRs, or discussions (if applicable) To automatically close an issue when this PR is merged, use closing keywords: - "closes #123" or "fixes #123" or "resolves #123" For regular references without auto-closing, just use: - "#123" or "See issue #123" Examples: - closes #456 (will auto-close issue #456 when PR is merged) - See #789 for context (will reference but not auto-close issue #789) --> - GitHub issue: - Feature PR: <!-- For LangChain employees, if applicable: --> - Linear issue: - Slack thread: ## Checklist <!-- Put an 'x' in all boxes that apply --> - [ ] I have read the [contributing guidelines](README.md) - [ ] I have tested my changes locally using `docs dev` - [ ] All code examples have been tested and work correctly - [ ] I have used **root relative** paths for internal links - [ ] I have updated navigation in `src/docs.json` if needed (Internal team members only / optional): Create a preview deployment as necessary using the [Create Preview Branch workflow](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) ## Additional notes <!-- Any other information that would be helpful for reviewers --> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 3d79e3b commit 935d6b8

File tree

2 files changed

+242
-0
lines changed

2 files changed

+242
-0
lines changed

‎src/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -362,6 +362,7 @@
362362
"langsmith/export-traces",
363363
"langsmith/compare-traces",
364364
"langsmith/share-trace",
365+
"langsmith/langsmith-mcp-server",
365366
"langsmith/platform-logs",
366367
"langsmith/data-export"
367368
]

‎src/langsmith/langsmith-mcp-server.mdx‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
---
2+
title: LangSmith MCP Server
3+
description: Use the Model Context Protocol (MCP) server to let language models fetch conversation history, prompts, runs, datasets, experiments, and billing from LangSmith.
4+
sidebarTitle: LangSmith MCP Server
5+
---
6+
7+
The **LangSmith MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that integrates with [LangSmith](https://smith.langchain.com). It lets MCP-compatible clients (for example, AI coding assistants) read [conversation history](/langsmith/observability-concepts#threads), [prompts](/langsmith/manage-prompts-programmatically), [runs and traces](/langsmith/observability-concepts#runs), [datasets](/langsmith/evaluation-concepts#datasets), [experiments](/langsmith/evaluation-concepts#experiment), and billing usage from your LangSmith workspace.
8+
9+
## Example use cases
10+
11+
- **Conversation history**: "Fetch the history of my conversation from thread 'thread-123' in project 'my-chatbot'"
12+
- **Prompt management**: "Get all public prompts" or "Pull the template for the 'legal-case-summarizer' prompt"
13+
- **Traces and runs**: "Fetch the latest 10 root runs from project 'alpha'" or "Get all runs for a trace by UUID"
14+
- **Datasets**: "List datasets of type chat" or "Read examples from dataset 'customer-support-qa'"
15+
- **Experiments**: "List experiments for dataset 'my-eval-set' with latency and cost metrics"
16+
- **Billing**: "Get billing usage for September 2025"
17+
18+
<Tip>
19+
**Use the server in code or Agent Builder**
20+
21+
- To connect and use remote MCP servers (including this one) in your Python application, see [MCP (Model Context Protocol)](/oss/langchain/mcp).
22+
- To connect and use this server in Agent Builder, see [Remote MCP servers](/langsmith/agent-builder-remote-mcp-servers).
23+
</Tip>
24+
25+
## Quickstart (hosted)
26+
27+
A hosted version of the LangSmith MCP Server is available over HTTP, so you can connect without running the server yourself.
28+
29+
- **URL:** `https://langsmith-mcp-server.onrender.com/mcp`
30+
- **Authentication:** Send your [LangSmith API key](/langsmith/create-account-api-key) in the `LANGSMITH-API-KEY` header.
31+
32+
<Note>
33+
The hosted instance is for [LangSmith Cloud](/langsmith/deploy-to-cloud). For a [self-hosted LangSmith](/langsmith/self-hosted) instance, run the server yourself and point it at your endpoint (see [Docker deployment](#docker-deployment-http-streamable)).
34+
</Note>
35+
36+
**Example (Cursor `mcp.json`):**
37+
38+
```json
39+
{
40+
"mcpServers": {
41+
"LangSmith MCP (Hosted)": {
42+
"url": "https://langsmith-mcp-server.onrender.com/mcp",
43+
"headers": {
44+
"LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here"
45+
}
46+
}
47+
}
48+
}
49+
```
50+
51+
Optional headers: `LANGSMITH-WORKSPACE-ID`, `LANGSMITH-ENDPOINT` (same as in [Environment variables](#environment-variables)).
52+
53+
## Available tools
54+
55+
The server exposes these tool groups for LangSmith.
56+
57+
### Conversation and threads
58+
59+
| Tool | Description |
60+
|------|-------------|
61+
| `get_thread_history` | Get message history for a conversation thread. Uses character-based pagination: pass `page_number` (1-based) and use the returned `total_pages` to request more pages. Optional: `max_chars_per_page`, `preview_chars`. |
62+
63+
### Prompt management
64+
65+
| Tool | Description |
66+
|------|-------------|
67+
| `list_prompts` | List prompts with optional filtering by visibility (public/private) and limit. |
68+
| `get_prompt_by_name` | Get a single prompt by exact name (details and template). |
69+
| `push_prompt` | Documentation-only: how to create and push prompts to LangSmith. |
70+
71+
### Traces and runs
72+
73+
| Tool | Description |
74+
|------|-------------|
75+
| `fetch_runs` | Fetch runs (traces, tools, chains, etc.) from one or more projects. Supports filters (`run_type`, `error`, `is_root`), FQL (`filter`, `trace_filter`, `tree_filter`), and ordering. When `trace_id` is set, results are character-based paginated; otherwise one batch up to `limit`. Always pass `limit` and `page_number`. |
76+
| `list_projects` | List projects with optional filtering by name, dataset, and detail level. |
77+
78+
### Datasets and examples
79+
80+
| Tool | Description |
81+
|------|-------------|
82+
| `list_datasets` | List datasets with filtering by ID, type, name, or metadata. |
83+
| `list_examples` | List examples from a dataset by dataset ID/name or example IDs; supports filter, metadata, splits, and optional `as_of` version. |
84+
| `read_dataset` | Read one dataset by ID or name. |
85+
| `read_example` | Read one example by ID, with optional `as_of` version. |
86+
| `create_dataset` | Documentation-only: how to create datasets. |
87+
| `update_examples` | Documentation-only: how to update dataset examples. |
88+
89+
### Experiments and evaluations
90+
91+
| Tool | Description |
92+
|------|-------------|
93+
| `list_experiments` | List experiment (reference) projects for a dataset. Requires `reference_dataset_id` or `reference_dataset_name`. Returns metrics (latency, cost, feedback). |
94+
| `run_experiment` | Documentation-only: how to run experiments and evaluations. |
95+
96+
### Billing
97+
98+
| Tool | Description |
99+
|------|-------------|
100+
| `get_billing_usage` | Get organization billing usage (e.g. trace counts) for a date range. Optional workspace filter. |
101+
102+
### Pagination (character-based)
103+
104+
Tools that return large payloads use **character-budget pagination** so responses stay within a size limit:
105+
106+
- **Used by:** `get_thread_history` and `fetch_runs` (when `trace_id` is set).
107+
- **Parameters:** Send `page_number` (1-based) on each request. Optional: `max_chars_per_page` (default 25000, max 30000), `preview_chars` (truncate long strings with "... (+N chars)").
108+
- **Response:** Includes `page_number`, `total_pages`, and the page payload. Request more by calling again with `page_number = 2`, then `3`, up to `total_pages`.
109+
- **Benefits:** Pages are built by character count, not item count; no cursor or server-side state—just page numbers.
110+
111+
## Installation (run locally)
112+
113+
If you prefer to run the server locally (or use a self-hosted LangSmith endpoint), install it and configure your MCP client.
114+
115+
### Prerequisites
116+
117+
1. Install [uv](https://github.com/astral-sh/uv) (Python package installer):
118+
```bash
119+
curl -LsSf https://astral.sh/uv/install.sh | sh
120+
```
121+
122+
2. Insll the package:
123+
```bash
124+
uv run pip install --upgrade langsmith-mcp-server
125+
```
126+
127+
### MCP client configuration
128+
129+
Add the server to your MCP client config. Use the path from `which uvx` for the `command` value.
130+
131+
**PyPI / uvx:**
132+
133+
```json
134+
{
135+
"mcpServers": {
136+
"LangSmith API MCP Server": {
137+
"command": "/path/to/uvx",
138+
"args": ["langsmith-mcp-server"],
139+
"env": {
140+
"LANGSMITH_API_KEY": "your_langsmith_api_key",
141+
"LANGSMITH_WORKSPACE_ID": "your_workspace_id",
142+
"LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
143+
}
144+
}
145+
}
146+
}
147+
```
148+
149+
**From source** (clone [langsmith-mcp-server](https://github.com/langchain-ai/langsmith-mcp-server) first):
150+
151+
```json
152+
{
153+
"mcpServers": {
154+
"LangSmith API MCP Server": {
155+
"command": "/path/to/uv",
156+
"args": [
157+
"--directory",
158+
"/path/to/langsmith-mcp-server",
159+
"run",
160+
"langsmith_mcp_server/server.py"
161+
],
162+
"env": {
163+
"LANGSMITH_API_KEY": "your_langsmith_api_key",
164+
"LANGSMITH_WORKSPACE_ID": "your_workspace_id",
165+
"LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
166+
}
167+
}
168+
}
169+
}
170+
```
171+
172+
Replace `/path/to/uv`, `/path/to/uvx`, and `/path/to/langsmith-mcp-server` with your actual paths.
173+
174+
## Docker deployment (HTTP-streamable)
175+
176+
You can run the server as an HTTP service with Docker so clients connect via the HTTP-streamable protocol.
177+
178+
1. Build and run:
179+
```bash
180+
docker build -t langsmith-mcp-server .
181+
docker run -p 8000:8000 langsmith-mcp-server
182+
```
183+
Use the [langsmith-mcp-server](https://github.com/langchain-ai/langsmith-mcp-server) repository for the Dockerfile and context.
184+
185+
2. Connect your MCP client to `http://localhost:8000/mcp` with the `LANGSMITH-API-KEY` header (and optional `LANGSMITH-WORKSPACE-ID`, `LANGSMITH-ENDPOINT`).
186+
187+
3. Health check (no auth):
188+
```bash
189+
curl http://localhost:8000/health
190+
```
191+
192+
For full Docker and HTTP-streamable details, see the [LangSmith MCP Server repository](https://github.com/langchain-ai/langsmith-mcp-server).
193+
194+
## Deployment overview
195+
196+
Use the **hosted** MCP server to connect to [LangSmith Cloud](/langsmith/cloud) (smith.langchain.com or eu.smith.langchain.com). Run the server **locally** ([Installation (run locally)](#installation-run-locally)) to connect to Cloud or [self-hosted LangSmith](/langsmith/self-hosted) (via `LANGSMITH_ENDPOINT`). If you use self-hosted LangSmith, you can instead run the server via the [Docker image](#docker-deployment-http-streamable) in your VPC so it can reach your self-hosted instance.
197+
198+
```mermaid
199+
flowchart LR
200+
subgraph Client["MCP client"]
201+
C[Cursor / Claude Code / etc.]
202+
end
203+
204+
subgraph CloudPath["Cloud"]
205+
H[Hosted MCP server]
206+
LSCloud[LangSmith Cloud]
207+
end
208+
209+
subgraph LocalPath["Local"]
210+
LocalServer[Local MCP server]
211+
end
212+
213+
subgraph SelfHostedPath["Self-hosted"]
214+
D[Docker MCP server]
215+
LSSelf[Self-hosted LangSmith]
216+
end
217+
218+
C --> H
219+
H --> LSCloud
220+
C --> LocalServer
221+
LocalServer --> LSCloud
222+
LocalServer --> LSSelf
223+
C --> D
224+
D --> LSSelf
225+
```
226+
227+
## Environment variables
228+
229+
| Variable | Required | Description |
230+
|----------|----------|-------------|
231+
| `LANGSMITH_API_KEY` | Yes | Your [LangSmith API key](/langsmith/create-account-api-key) for authentication. |
232+
| `LANGSMITH_WORKSPACE_ID` | No | Workspace ID when your API key has access to multiple workspaces. |
233+
| `LANGSMITH_ENDPOINT` | No | API endpoint URL (for [self-hosted](/langsmith/self-hosted) or custom regions). Default: `https://api.smith.langchain.com`. |
234+
235+
For the **hosted** server, use the same names as **headers**: `LANGSMITH-API-KEY`, `LANGSMITH-WORKSPACE-ID`, `LANGSMITH-ENDPOINT`.
236+
237+
## TypeScript implementation
238+
239+
A community-maintained TypeScript/Node.js port of the official Python server is available. To run it: `LANGSMITH_API_KEY=your-key npx langsmith-mcp-server`.
240+
241+
Source and package: [GitHub](https://github.com/amitrechavia/langsmith-mcp-server-js) · [npm](https://www.npmjs.com/package/langsmith-mcp-server). Maintained by [amitrechavia](https://github.com/amitrechavia).

0 commit comments

Comments
 (0)