LangSmith MCP Server

Um servidor MCP para buscar histórico de conversas e prompts da plataforma de observabilidade LangSmith.

Documentação

🦜🛠️ LangSmith MCP Server

LangSmith MCP Hero

Um servidor Model Context Protocol (MCP) pronto para produção que oferece integração perfeita com a plataforma de observabilidade LangSmith. Este servidor permite que modelos de linguagem busquem histórico de conversas, prompts, execuções e traces, conjuntos de dados, experimentos e uso de faturamento do LangSmith.

📋 Casos de Uso de Exemplo

O servidor permite capacidades poderosas, incluindo:

💬 Histórico de Conversas: "Busque o histórico da minha conversa do thread 'thread-123' no projeto 'my-chatbot'" (paginado por orçamento de caracteres)
📚 Gerenciamento de Prompts: "Obtenha todos os prompts públicos no meu workspace" / "Puxe o template para o prompt 'legal-case-summarizer'"
🔍 Traces e Execuções: "Busque as 10 execuções raiz mais recentes do projeto 'alpha'" / "Obtenha todas as execuções para o trace <uuid> (página 2 de 5)"
📊 Conjuntos de Dados: "Liste conjuntos de dados do tipo chat" / "Leia exemplos do conjunto de dados 'customer-support-qa'"
🧪 Experimentos: "Liste experimentos para o conjunto de dados 'my-eval-set' com métricas de latência e custo"
📈 Faturamento: "Obtenha o uso de faturamento para setembro de 2025"

🚀 Início Rápido

Uma versão hospedada do LangSmith MCP Server está disponível via transporte HTTP-streamable, para que você possa se conectar sem executar o servidor você mesmo:

URL: https://langsmith-mcp-server.onrender.com/mcp
Hospedagem: Render, construído a partir deste repositório público usando o Dockerfile do projeto.

Use-o como qualquer servidor MCP HTTP-streamable: aponte seu cliente para a URL e envie sua chave de API LangSmith no cabeçalho LANGSMITH-API-KEY. Não é necessária instalação local ou Docker.

Exemplo (Cursor mcp.json):

{
  "mcpServers": {
    "LangSmith MCP (Hosted)": {
      "url": "https://langsmith-mcp-server.onrender.com/mcp",
      "headers": {
        "LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here"
      }
    }
  }
}

Cabeçalhos opcionais: LANGSMITH-WORKSPACE-ID, LANGSMITH-ENDPOINT (mesmos da seção Implantação com Docker abaixo).

Nota: Esta instância implantada é destinada ao LangSmith Cloud. Se você usa uma instância LangSmith auto-hospedada, execute o servidor você mesmo e aponte-o para seu endpoint—veja a seção Implantação com Docker abaixo.

🛠️ Ferramentas Disponíveis

O LangSmith MCP Server fornece as seguintes ferramentas para integração com o LangSmith.

💬 Conversas e Threads

Nome da Ferramenta	Descrição
`get_thread_history`	Recupera o histórico de mensagens de um thread de conversa. Usa paginação baseada em caracteres: passe `page_number` (baseado em 1) e use o `total_pages` retornado para solicitar mais páginas. Os opcionais `max_chars_per_page` e `preview_chars` controlam o tamanho da página e a truncagem de strings longas.

📚 Gerenciamento de Prompts

Nome da Ferramenta	Descrição
`list_prompts`	Busca prompts do LangSmith com filtragem opcional por visibilidade (público/privado) e limite.
`get_prompt_by_name`	Obtém um prompt específico pelo seu nome exato, retornando os detalhes do prompt e o template.
`push_prompt`	Somente documentação: como criar e enviar prompts para o LangSmith.

🔍 Traces e Execuções

Nome da Ferramenta	Descrição
`fetch_runs`	Busca execuções do LangSmith (traces, ferramentas, chains, etc.) de um ou mais projetos. Suporta filtros (run_type, error, is_root), FQL (`filter`, `trace_filter`, `tree_filter`) e ordenação. Quando `trace_id` está definido, retorna páginas paginadas por caracteres; caso contrário, retorna um lote de até `limit`. Sempre passe `limit` e `page_number`.
`list_projects`	Lista projetos LangSmith com filtragem opcional por nome, conjunto de dados e nível de detalhe (simplificado vs completo).

📊 Conjuntos de Dados e Exemplos

Nome da Ferramenta	Descrição
`list_datasets`	Busca conjuntos de dados com filtragem por ID, tipo, nome, substring do nome ou metadados.
`list_examples`	Busca exemplos de um conjunto de dados por ID/nome do conjunto ou IDs de exemplo, com filtro, metadados, divisões e versão `as_of` opcional.
`read_dataset`	Lê um único conjunto de dados por ID ou nome.
`read_example`	Lê um único exemplo por ID, com versão `as_of` opcional.
`create_dataset`	Somente documentação: como criar conjuntos de dados no LangSmith.
`update_examples`	Somente documentação: como atualizar exemplos de conjuntos de dados no LangSmith.

🧪 Experimentos e Avaliações

Nome da Ferramenta	Descrição
`list_experiments`	Lista projetos de experimento (projetos de referência) para um conjunto de dados. Requer `reference_dataset_id` ou `reference_dataset_name`. Retorna métricas-chave (latência, custo, estatísticas de feedback).
`run_experiment`	Somente documentação: como executar experimentos e avaliações no LangSmith.

📈 Uso e Faturamento

Nome da Ferramenta	Descrição
`get_billing_usage`	Busca o uso de faturamento da organização (ex.: contagens de traces) para um intervalo de datas. Filtro de workspace opcional; retorna métricas com nomes de workspace embutidos.

📄 Paginação (baseada em caracteres)

Várias ferramentas usam paginação sem estado, com orçamento de caracteres para que as respostas permaneçam dentro de um limite de tamanho e funcionem bem com clientes LLM:

Onde é usada: get_thread_history e fetch_runs (quando trace_id está definido).
Parâmetros: Você envia page_number (baseado em 1) em cada solicitação. Opcionais: max_chars_per_page (padrão 25000, limite 30000) e preview_chars (trunca strings longas com "… (+N caracteres)").
Resposta: Cada resposta inclui page_number, total_pages e o payload da página (result para mensagens, runs para execuções). Para obter mais, chame novamente com page_number = 2, depois 3, até total_pages.
Por que é útil: As páginas são construídas pela contagem de caracteres JSON, não pela contagem de itens, então cada página cabe em um tamanho fixo. Sem cursor ou estado no servidor—apenas números de página inteiros.

🛠️ Opções de Instalação

📝 Pré-requisitos Gerais

Instale o uv (um instalador e resolvedor de pacotes Python rápido):
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Clone este repositório e navegue até o diretório do projeto:

git clone https://github.com/langchain-ai/langsmith-mcp-server.git
cd langsmith-mcp-server

🔌 Integração com Cliente MCP

Depois de ter o LangSmith MCP Server, você pode integrá-lo com vários clientes compatíveis com MCP. Você tem duas opções de instalação:

📦 A partir do PyPI

Instale o pacote:

uv run pip install --upgrade langsmith-mcp-server

Adicione à configuração MCP do seu cliente:

{
    "mcpServers": {
        "LangSmith API MCP Server": {
            "command": "/path/to/uvx",
            "args": [
                "langsmith-mcp-server"
            ],
            "env": {
                "LANGSMITH_API_KEY": "your_langsmith_api_key",
                "LANGSMITH_WORKSPACE_ID": "your_workspace_id",
                "LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
            }
        }
    }
}

⚙️ A partir do Código Fonte

Adicione a seguinte configuração às configurações do seu cliente MCP (execute a partir da raiz do projeto para que o pacote seja encontrado):

{
    "mcpServers": {
        "LangSmith API MCP Server": {
            "command": "/path/to/uv",
            "args": [
                "--directory",
                "/path/to/langsmith-mcp-server",
                "run",
                "langsmith_mcp_server/server.py"
            ],
            "env": {
                "LANGSMITH_API_KEY": "your_langsmith_api_key",
                "LANGSMITH_WORKSPACE_ID": "your_workspace_id",
                "LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
            }
        }
    }
}

Substitua os seguintes placeholders:

/path/to/uv: O caminho absoluto para sua instalação do uv (ex.: /Users/username/.local/bin/uv). Você pode encontrá-lo com which uv.
/path/to/langsmith-mcp-server: O caminho absoluto para a raiz do projeto (o diretório que contém pyproject.toml e langsmith_mcp_server/).
your_langsmith_api_key: Sua chave de API LangSmith (obrigatória).
your_workspace_id: Seu ID de workspace LangSmith (opcional, para chaves de API com escopo em vários workspaces).
https://api.smith.langchain.com: O endpoint da API LangSmith (opcional, padrão para o endpoint padrão).

Exemplo de configuração (PyPI/uvx):

{
    "mcpServers": {
        "LangSmith API MCP Server": {
            "command": "/path/to/uvx",
            "args": ["langsmith-mcp-server"],
            "env": {
                "LANGSMITH_API_KEY": "lsv2_pt_your_key_here",
                "LANGSMITH_WORKSPACE_ID": "your_workspace_id",
                "LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
            }
        }
    }
}

Copie esta configuração para Cursor → Configurações MCP (substitua /path/to/uvx pela saída de which uvx).

LangSmith Cursor Integration

🔧 Cabeçalhos (invocação de ferramentas)

Ao conectar via HTTP (ex.: HTTP streamable ou um endpoint MCP hospedado), o servidor usa cabeçalhos para autenticação e configuração. Seu cliente MCP deve enviá-los em cada solicitação; nenhuma variável de ambiente é necessária para a invocação de ferramentas.

Cabeçalho	Obrigatório	Descrição
`LANGSMITH-API-KEY`	✅ Sim	Sua chave de API LangSmith para chamadas de ferramentas (listar prompts, buscar execuções, etc.)
`LANGSMITH-WORKSPACE-ID`	❌ Não	ID do workspace para chaves de API com escopo em vários workspaces
`LANGSMITH-ENDPOINT`	❌ Não	URL personalizada do endpoint da API (para auto-hospedado ou região da UE)

Cabeçalhos opcionais usados apenas quando o monitoramento do servidor está habilitado (para agrupar traces por sessão):

Cabeçalho	Descrição
`mcp-session-id`	ID de sessão ou thread; armazenado nos metadados do trace como `session_id`
`x-session-id`	Fallback se `mcp-session-id` não estiver definido
`x-request-id`	Fallback para agrupamento com escopo de solicitação

Transporte Stdio: Ao executar o servidor via stdio (ex.: uvx langsmith-mcp-server), não há cabeçalhos. O servidor recorre às variáveis de ambiente LANGSMITH_API_KEY, LANGSMITH_WORKSPACE_ID e LANGSMITH_ENDPOINT no ambiente do processo para que a invocação de ferramentas ainda funcione.

🔧 Variáveis de ambiente

As variáveis de ambiente não são usadas para invocação de ferramentas ao usar HTTP (os cabeçalhos são). Elas são usadas para:

Transporte Stdio – fallback para credenciais quando não existem cabeçalhos (veja acima).
Testes de carga – ex.: tests/load_test_sessions.py lê LANGSMITH_API_KEY do ambiente (ou um arquivo .env na raiz do projeto).
Monitoramento opcional do servidor – rastreamento de chamadas de ferramentas para uma segunda instância LangSmith (veja abaixo).

Variável	Usada para	Descrição
`LANGSMITH_API_KEY`	Fallback Stdio, testes de carga	Chave de API LangSmith (quando não fornecida via cabeçalhos)
`LANGSMITH_WORKSPACE_ID`	Fallback Stdio	ID do workspace (opcional)
`LANGSMITH_ENDPOINT`	Fallback Stdio	URL personalizada do endpoint (opcional)

Opcional: Monitoramento de chamadas de ferramentas para uma segunda instância LangSmith

Você pode registrar cada chamada de ferramenta MCP (com entradas e saídas) em um projeto LangSmith separado para monitoramento e análise. Defina-os no seu ambiente (ex.: em um arquivo .env na raiz do projeto; o servidor carrega .env via python-dotenv):

Variável	Obrigatório	Descrição
`LANGSMITH_MONITORING_API_KEY`	Sim (para habilitar)	Chave de API para a instância LangSmith usada para monitoramento
`LANGSMITH_MONITORING_ENDPOINT`	Não	URL do endpoint (padrão: cloud)
`LANGSMITH_MONITORING_WORKSPACE_ID`	Não	ID do workspace para a instância de monitoramento
`LANGSMITH_MONITORING_PROJECT`	Não	Nome do projeto para traces de monitoramento (padrão: `mcp-server-monitoring`)
`LANGSMITH_TRACING`	Sim (para enviar traces)	Defina como `true` para que os traces sejam enviados ao LangSmith (instrumentação personalizada)

Cada execução de ferramenta é rastreada com run_type="tool" e um session_id nos metadados (do cabeçalho mcp-session-id, x-session-id ou x-request-id ao usar HTTP, ou gerado por solicitação).

Se você usar o LangSmith MCP Server hospedado, dados anônimos de uso são enviados a um projeto LangSmith separado para que possamos iterar e melhorar o produto.

🐳 Implantação com Docker (HTTP-Streamable)

O LangSmith MCP Server pode ser implantado como um servidor HTTP usando Docker, permitindo acesso remoto via protocolo HTTP-streamable.

Construindo a Imagem Docker

docker build -t langsmith-mcp-server .

Executando com Docker

docker run -p 8000:8000 langsmith-mcp-server

A chave de API é fornecida via cabeçalho LANGSMITH-API-KEY ao conectar, portanto nenhuma variável de ambiente é necessária para o protocolo HTTP-streamable.

Conectando com o Protocolo HTTP-Streamable

Depois que o contêiner Docker estiver em execução, você pode se conectar a ele usando o transporte HTTP-streamable. O servidor aceita autenticação via cabeçalhos:

Cabeçalho obrigatório:

LANGSMITH-API-KEY: Sua chave de API LangSmith

Cabeçalhos opcionais:

LANGSMITH-WORKSPACE-ID: ID do workspace para chaves de API com escopo em vários workspaces
LANGSMITH-ENDPOINT: URL personalizada do endpoint da API (para auto-hospedado ou região da UE)

Exemplo de configuração do cliente:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {
    "LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here",
    # Optional:
    # "LANGSMITH-WORKSPACE-ID": "your_workspace_id",
    # "LANGSMITH-ENDPOINT": "https://api.smith.langchain.com",
}

async with streamablehttp_client("http://localhost:8000/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # Use the session to call tools, list prompts, etc.

Integração com Cursor

Para adicionar o LangSmith MCP Server ao Cursor usando o protocolo HTTP-streamable, adicione o seguinte ao seu arquivo de configuração mcp.json:

{
  "mcpServers": {
    "HTTP-Streamable LangSmith MCP Server": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here"
      }
    }
  }
}

Cabeçalhos opcionais:

{
  "mcpServers": {
    "HTTP-Streamable LangSmith MCP Server": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here",
        "LANGSMITH-WORKSPACE-ID": "your_workspace_id",
        "LANGSMITH-ENDPOINT": "https://api.smith.langchain.com"
      }
    }
  }
}

Certifique-se de que o servidor esteja em execução antes de conectar o Cursor a ele.

Verificação de Saúde

O servidor fornece um endpoint de verificação de saúde:

curl http://localhost:8000/health

Este endpoint não requer autenticação e retorna "LangSmith MCP server is running" quando o servidor está saudável.

🧪 Desenvolvimento e Contribuição

Pré-requisitos

Python 3.10+ (3.11+ recomendado)
uv – instale com curl -LsSf https://astral.sh/uv/install.sh | sh
Chave da API LangSmith – de smith.langchain.com
Node.js (opcional) – apenas se quiser usar o MCP Inspector para testar o servidor (stdio ou streamable-http)

Configuração

git clone https://github.com/langchain-ai/langsmith-mcp-server.git
cd langsmith-mcp-server

uv sync                    # Install dependencies
uv sync --group test       # Include test dependencies (pytest, ruff, mypy)

uvx langsmith-mcp-server   # Verify CLI runs (stdio)

Fluxo de desenvolvimento

Edite o código em langsmith_mcp_server/ ou tests/.
Formate e faça lint (obrigatório antes de commitar):
```
make format
make lint
```

Execute os testes:

make test
# Or a single file:
make test TEST_FILE=tests/tools/test_dataset_tools.py

Verificação de tipos (opcional): uv run mypy langsmith_mcp_server/

Testando com o MCP Inspector

Você pode testar o servidor com o MCP Inspector usando stdio ou streamable-http.

Inicie o MCP Inspector:
```
npx @modelcontextprotocol/inspector@latest
```
Abra http://localhost:6274 no seu navegador.
Conecte-se no Inspector:
- Stdio: Escolha o transporte stdio e configure o comando do servidor (ex.: uv run langsmith-mcp-server) e defina LANGSMITH_API_KEY no ambiente.
- Streamable HTTP: Inicie o servidor primeiro (uv run uvicorn langsmith_mcp_server.server:app --host 0.0.0.0 --port 8000 ou Docker), depois escolha streamable-http, URL http://localhost:8000/mcp, e adicione o cabeçalho LANGSMITH-API-KEY = sua chave de API.

Teste de carga

Um teste de carga baseado em sessão abre muitas sessões MCP e chama a ferramenta list_prompts em cada uma, usando langchain-mcp-adapters. Execute pela CLI (sem interface gráfica). O servidor deve estar em execução primeiro.

uv sync --group load
# Terminal 1: start the server
uv run uvicorn langsmith_mcp_server.server:app --host 0.0.0.0 --port 8000
# Terminal 2: run the load test
uv run python tests/load_test_sessions.py --sessions 20 --calls-per-session 3

Opções

Opção	Padrão	Descrição
`--url`	`http://localhost:8000/mcp`	URL do endpoint MCP
`--api-key`	de `.env`	`LANGSMITH_API_KEY` (ou defina na raiz do projeto `.env`)
`--sessions`	10	Número de sessões simultâneas
`--calls-per-session`	3	`list_prompts` chamadas por sessão
`--debug`	desativado	Imprime logs passo a passo e o primeiro traceback de erro
`--report` PATH	—	Escreve um relatório após a execução (veja abaixo)

Relatório

Use --report PATH para escrever um relatório JSON após o teste (ex.: --report load_test_report cria load_test_report.json com configuração, resumo, resultados por sessão e primeiro erro).

uv run python tests/load_test_sessions.py --sessions 5 --report load_test_report
# Creates: load_test_report.json (in current directory)

Checklist de contribuição

Antes de abrir um PR:

make format e make lint passam
make test passa
Novas ferramentas ou comportamentos estão documentados (ex.: em CLAUDE.md se você alterar arquitetura ou ferramentas)
O tratamento de erros nas ferramentas retorna {"error": "..."} em vez de lançar exceções

Para mais detalhes (adicionar ferramentas, padrões de código, solução de problemas), consulte CLAUDE.md.

📄 Licença

Este projeto é distribuído sob a Licença MIT. Para termos e condições detalhados, consulte o arquivo LICENSE.

Feito com ❤️ pela equipe LangChain