LangSmith Tool Server

The LangSmith Tool Server is our MCP Framework that powers the tools available in the LangSmith Agent Builder. This framework enables you to build and deploy custom tools that can be integrated with your agents. It provides a standardized way to create, deploy, and manage tools with built-in authentication and authorization.

The PyPi package that defines the framework is available here.

Quick start

Install the LangSmith Tool Server and LangChain CLI:

pip install langsmith-tool-server
pip install langchain-cli-v2

Create a new toolkit:

langchain tools new my-toolkit
cd my-toolkit

This creates a toolkit with the following structure:

my-toolkit/
├── pyproject.toml
├── toolkit.toml
└── my_toolkit/
    ├── __init__.py
    ├── auth.py
    └── tools/
        ├── __init__.py
        └── ...

Define your tools using the @tool decorator:

from langsmith_tool_server import tool

@tool
def hello(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

@tool
def add(x: int, y: int) -> int:
    """Add two numbers."""
    return x + y

TOOLS = [hello, add]

Run the server:

langchain tools serve

Your tool server will start on http://localhost:8000.

Simple client example

Here’s a simple example that lists available tools and calls the add tool:

import asyncio
import aiohttp

async def mcp_request(url: str, method: str, params: dict = None):
    async with aiohttp.ClientSession() as session:
        payload = {"jsonrpc": "2.0", "method": method, "params": params or {}, "id": 1}
        async with session.post(f"{url}/mcp", json=payload) as response:
            return await response.json()

async def main():
    url = "http://localhost:8000"

    tools = await mcp_request(url, "tools/list")
    print(f"Tools: {tools}")

    result = await mcp_request(url, "tools/call", {"name": "add", "arguments": {"a": 5, "b": 3}})
    print(f"Result: {result}")

asyncio.run(main())

Adding OAuth authentication

For tools that need to access third-party APIs (like Google, GitHub, Slack, etc.), you can use OAuth authentication with Agent Auth.

Before using OAuth in your tools, you’ll need to configure an OAuth provider in your LangSmith workspace settings. See the Agent Auth documentation for setup instructions.

Once configured, specify the auth_provider in your tool decorator:

from langsmith_tool_server import tool, Context
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

@tool(
    auth_provider="google",
    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
    integration="gmail"
)
async def read_emails(context: Context, max_results: int = 10) -> str:
    """Read recent emails from Gmail."""
    credentials = Credentials(token=context.token)
    service = build('gmail', 'v1', credentials=credentials)
    # ... Gmail API calls
    return f"Retrieved {max_results} emails"

Tools with auth_provider must:

• Have context: Context as the first parameter
• Specify at least one scope
• Use context.token to make authenticated API calls

Using as an MCP gateway

The LangSmith Tool Server can act as an MCP gateway, aggregating tools from multiple MCP servers into a single endpoint. Configure MCP servers in your toolkit.toml:

[toolkit]
name = "my-toolkit"
tools = "./my_toolkit/__init__.py:TOOLS"

[[mcp_servers]]
name = "weather"
transport = "streamable_http"
url = "http://localhost:8001/mcp/"

[[mcp_servers]]
name = "math"
transport = "stdio"
command = "python"
args = ["-m", "mcp_server_math"]

All tools from connected MCP servers are exposed through your server’s /mcp endpoint. MCP tools are prefixed with their server name to avoid conflicts (e.g., weather.get_forecast, math.add).

Custom authentication

Custom authentication allows you to validate requests and integrate with your identity provider. Define an authentication handler in your auth.py file:

from langsmith_tool_server import Auth

auth = Auth()

@auth.authenticate
async def authenticate(authorization: str = None) -> dict:
    """Validate requests and return user identity."""
    if not authorization or not authorization.startswith("Bearer "):
        raise auth.exceptions.HTTPException(
            status_code=401,
            detail="Unauthorized"
        )

    token = authorization.replace("Bearer ", "")
    # Validate token with your identity provider
    user = await verify_token_with_idp(token)

    return {"identity": user.id}

The handler runs on every request and must return a dict with identity (and optionally permissions).

Using remote MCP servers

Agent Builder can discover and use tools from remote Model Context Protocol (MCP) servers. This lets you connect to external MCP servers and use their tools in your agents.

Configuration

Configure remote MCP servers in your LangSmith workspace:

1. Navigate to your workspace settings in the LangSmith UI.
2. Add your MCP server URL and any required headers (for example, Authorization: Bearer {{MCP_TOKEN}}).
3. Agent Builder automatically discovers tools from the server and applies the configured headers when calling tools.

Use workspace secret placeholders like {{MCP_TOKEN}} in headers. The platform resolves these from your workspace secrets at runtime.

How it works

• Agent Builder discovers tools from remote MCP servers via the standard MCP protocol.
• Headers configured in your workspace are automatically attached when fetching tools or calling them.
• Tools from remote servers are available alongside built-in tools in Agent Builder.

---

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.