LangSmith MCP Server (TypeScript)

A TypeScript implementation of the Model Context Protocol (MCP) server for LangSmith. This is a full port of the official Python LangSmith MCP Server with 100% functional parity.

Example Use Cases

The server enables powerful capabilities including:

• Conversation History: "Fetch the history of my conversation from thread 'thread-123' in project 'my-chatbot'" (paginated by character budget)
• Prompt Management: "Get all public prompts in my workspace" / "Pull the template for the 'legal-case-summarizer' prompt"
• Traces & Runs: "Fetch the latest 10 root runs from project 'alpha'" / "Get all runs for trace <uuid> (page 2 of 5)"
• Datasets: "List datasets of type chat" / "Read examples from dataset 'customer-support-qa'"
• Experiments: "List experiments for dataset 'my-eval-set' with latency and cost metrics"
• Billing: "Get billing usage for September 2025"

Quick Start

LANGSMITH_API_KEY=your-key npx langsmith-mcp-server

Available Tools

The LangSmith MCP Server provides the following tools for integration with LangSmith.

Conversation & Threads

Tool Name	Description
get_thread_history	Retrieve message history for a conversation thread. Uses char-based pagination: pass page_number (1-based), and use returned total_pages to request more pages. Optional max_chars_per_page and preview_chars control page size and long-string truncation.

Prompt Management

Tool Name	Description
list_prompts	Fetch prompts from LangSmith with optional filtering by visibility (public/private) and limit.
get_prompt_by_name	Get a specific prompt by its exact name, returning the prompt details and template.
push_prompt	Documentation-only: how to create and push prompts to LangSmith.

Traces & Runs

Tool Name	Description
fetch_runs	Fetch LangSmith 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. All results are automatically paginated by character budget. Always pass limit and page_number.
list_projects	List LangSmith projects with optional filtering by name, dataset, and detail level (simplified vs full).

Datasets & Examples

Tool Name	Description
list_datasets	Fetch datasets with filtering by ID, type, name, name substring, or metadata.
list_examples	Fetch examples from a dataset by dataset ID/name or example IDs, with filter, metadata, splits, and optional as_of version.
read_dataset	Read a single dataset by ID or name.
read_example	Read a single example by ID, with optional as_of version.
create_dataset	Documentation-only: how to create datasets in LangSmith.
update_examples	Documentation-only: how to update dataset examples in LangSmith.

Experiments & Evaluations

Tool Name	Description
list_experiments	List experiment projects (reference projects) for a dataset. Requires reference_dataset_id or reference_dataset_name. Returns key metrics (latency, cost, feedback stats).
run_experiment	Documentation-only: how to run experiments and evaluations in LangSmith.

Usage & Billing

Tool Name	Description
get_billing_usage	Fetch organization billing usage (e.g. trace counts) for a date range. Optional workspace filter; returns metrics with workspace names inline.

Pagination (char-based)

Several tools use stateless, character-budget pagination so responses stay within a size limit and work well with LLM clients:

• Where it's used: get_thread_history and fetch_runs.
• Parameters: You send page_number (1-based) on every request. Optional: max_chars_per_page (default 25000, cap 30000) and preview_chars (truncate long strings with "... (+N chars)").
• Response: Each response includes page_number, total_pages, and the page payload (result for messages, runs for runs). To get more, call again with page_number = 2, then 3, up to total_pages.
• Why it's useful: Pages are built by JSON character count, not item count, so each page fits within a fixed size. No cursor or server-side state -- just integer page numbers.

Installation

From npm

npx langsmith-mcp-server

MCP Client Integration

Cursor / Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "langsmith": {
      "command": "npx",
      "args": ["langsmith-mcp-server"],
      "env": {
        "LANGSMITH_API_KEY": "your-key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description	Example
LANGSMITH_API_KEY	Yes	Your LangSmith API key for authentication	lsv2_pt_1234567890
LANGSMITH_WORKSPACE_ID	No	Workspace ID for API keys scoped to multiple workspaces	your_workspace_id
LANGSMITH_ENDPOINT	No	Custom API endpoint URL (for self-hosted or EU region)	https://eu.api.smith.langchain.com

Notes:

• Only LANGSMITH_API_KEY is required for basic functionality
• LANGSMITH_WORKSPACE_ID is useful when your API key has access to multiple workspaces
• LANGSMITH_ENDPOINT allows you to use custom endpoints for self-hosted LangSmith installations or the EU region

Development and Contributing

Setup

# Clone the repository
git clone https://github.com/langchain-ai/langsmith-mcp-server-js.git
cd langsmith-mcp-server-js

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
LANGSMITH_API_KEY=your-key npm run dev

# Run production build
LANGSMITH_API_KEY=your-key npm start

Testing

# Run unit tests
npm test

MCP Inspector

For interactive development and debugging, use the MCP Inspector:

LANGSMITH_API_KEY=your-key npx @modelcontextprotocol/inspector npx .

This opens a browser UI where you can browse all tools, inspect their schemas, and invoke them interactively.

Verify the server responds

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | LANGSMITH_API_KEY=test npx . 2>/dev/null

Architecture

This is a direct port of the Python LangSmith MCP Server with the same module structure:

src/
  index.ts                    # Entry point (stdio transport)
  server.ts                   # McpServer setup
  common/
    helpers.ts                # Client creation, data conversion utilities
    pagination.ts             # Char-based stateless pagination
    formatters.ts             # Message extraction and formatting
  services/
    register-tools.ts         # MCP tool registration with Zod schemas
    tools/
      prompts.ts              # Prompt management tools
      traces.ts               # Trace/run/project tools
      datasets.ts             # Dataset and example tools
      experiments.ts          # Experiment listing tools
      usage.ts                # Billing/usage REST API tools

Contributing

This TypeScript implementation is a community port of the official Python LangSmith MCP Server by LangChain.

Contributions are welcome! Please open an issue or pull request on GitHub.

License

This project is distributed under the MIT License. For detailed terms and conditions, please refer to the LICENSE file.