LangSmith MCP Server

Un servidor MCP para obtener el historial de conversaciones y prompts desde la plataforma de observabilidad LangSmith.

Documentación

🦜🛠️ LangSmith MCP Server

LangSmith MCP Hero

Un servidor Model Context Protocol (MCP) listo para producción que proporciona una integración perfecta con la plataforma de observabilidad LangSmith. Este servidor permite a los modelos de lenguaje obtener historial de conversaciones, prompts, ejecuciones y trazas, conjuntos de datos, experimentos y uso de facturación desde LangSmith.

📋 Casos de uso de ejemplo

El servidor habilita capacidades potentes, incluyendo:

💬 Historial de conversaciones: "Obtén el historial de mi conversación del hilo 'thread-123' en el proyecto 'my-chatbot'" (paginado por presupuesto de caracteres)
📚 Gestión de prompts: "Obtén todos los prompts públicos en mi espacio de trabajo" / "Trae la plantilla del prompt 'legal-case-summarizer'"
🔍 Trazas y ejecuciones: "Obtén las últimas 10 ejecuciones raíz del proyecto 'alpha'" / "Obtén todas las ejecuciones de la traza <uuid> (página 2 de 5)"
📊 Conjuntos de datos: "Lista los conjuntos de datos de tipo chat" / "Lee ejemplos del conjunto de datos 'customer-support-qa'"
🧪 Experimentos: "Lista los experimentos del conjunto de datos 'my-eval-set' con métricas de latencia y costo"
📈 Facturación: "Obtén el uso de facturación para septiembre de 2025"

🚀 Inicio rápido

Una versión alojada del LangSmith MCP Server está disponible mediante transporte HTTP-streamable, por lo que puedes conectarte sin ejecutar el servidor tú mismo:

URL: https://langsmith-mcp-server.onrender.com/mcp
Alojamiento: Render, construido desde este repositorio público usando el Dockerfile del proyecto.

Úsalo como cualquier servidor MCP HTTP-streamable: apunta tu cliente a la URL y envía tu clave de API de LangSmith en el encabezado LANGSMITH-API-KEY. No se requiere instalación local ni Docker.

Ejemplo (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"
      }
    }
  }
}

Encabezados opcionales: LANGSMITH-WORKSPACE-ID, LANGSMITH-ENDPOINT (igual que en la sección Implementación con Docker más abajo).

Nota: Esta instancia implementada está pensada para LangSmith Cloud. Si usas una instancia de LangSmith autoalojada, ejecuta el servidor tú mismo y apúntalo a tu endpoint—consulta la sección Implementación con Docker más abajo.

🛠️ Herramientas disponibles

El LangSmith MCP Server proporciona las siguientes herramientas para la integración con LangSmith.

💬 Conversaciones e hilos

Nombre de la herramienta	Descripción
`get_thread_history`	Recupera el historial de mensajes de un hilo de conversación. Usa paginación basada en caracteres: pasa `page_number` (basado en 1), y usa el `total_pages` devuelto para solicitar más páginas. Los `max_chars_per_page` y `preview_chars` opcionales controlan el tamaño de página y el truncamiento de cadenas largas.

📚 Gestión de prompts

Nombre de la herramienta	Descripción
`list_prompts`	Obtiene prompts de LangSmith con filtrado opcional por visibilidad (público/privado) y límite.
`get_prompt_by_name`	Obtiene un prompt específico por su nombre exacto, devolviendo los detalles del prompt y la plantilla.
`push_prompt`	Solo documentación: cómo crear y enviar prompts a LangSmith.

🔍 Trazas y ejecuciones

Nombre de la herramienta	Descripción
`fetch_runs`	Obtiene ejecuciones de LangSmith (trazas, herramientas, cadenas, etc.) de uno o más proyectos. Admite filtros (run_type, error, is_root), FQL (`filter`, `trace_filter`, `tree_filter`) y ordenamiento. Cuando `trace_id` está configurado, devuelve páginas paginadas por caracteres; de lo contrario, devuelve un lote de hasta `limit`. Siempre pasa `limit` y `page_number`.
`list_projects`	Lista proyectos de LangSmith con filtrado opcional por nombre, conjunto de datos y nivel de detalle (simplificado vs. completo).

📊 Conjuntos de datos y ejemplos

Nombre de la herramienta	Descripción
`list_datasets`	Obtiene conjuntos de datos con filtrado por ID, tipo, nombre, subcadena de nombre o metadatos.
`list_examples`	Obtiene ejemplos de un conjunto de datos por ID/nombre del conjunto de datos o IDs de ejemplo, con filtro, metadatos, divisiones y versión `as_of` opcional.
`read_dataset`	Lee un único conjunto de datos por ID o nombre.
`read_example`	Lee un único ejemplo por ID, con versión `as_of` opcional.
`create_dataset`	Solo documentación: cómo crear conjuntos de datos en LangSmith.
`update_examples`	Solo documentación: cómo actualizar ejemplos de conjuntos de datos en LangSmith.

🧪 Experimentos y evaluaciones

Nombre de la herramienta	Descripción
`list_experiments`	Lista proyectos de experimentos (proyectos de referencia) para un conjunto de datos. Requiere `reference_dataset_id` o `reference_dataset_name`. Devuelve métricas clave (latencia, costo, estadísticas de retroalimentación).
`run_experiment`	Solo documentación: cómo ejecutar experimentos y evaluaciones en LangSmith.

📈 Uso y facturación

Nombre de la herramienta	Descripción
`get_billing_usage`	Obtiene el uso de facturación de la organización (p. ej., recuentos de trazas) para un rango de fechas. Filtro de espacio de trabajo opcional; devuelve métricas con nombres de espacios de trabajo integrados.

📄 Paginación (basada en caracteres)

Varias herramientas usan paginación sin estado por presupuesto de caracteres para que las respuestas se mantengan dentro de un límite de tamaño y funcionen bien con clientes LLM:

Dónde se usa: get_thread_history y fetch_runs (cuando trace_id está configurado).
Parámetros: Envías page_number (basado en 1) en cada solicitud. Opcional: max_chars_per_page (predeterminado 25000, máximo 30000) y preview_chars (trunca cadenas largas con "… (+N caracteres)").
Respuesta: Cada respuesta incluye page_number, total_pages y la carga útil de la página (result para mensajes, runs para ejecuciones). Para obtener más, llama de nuevo con page_number = 2, luego 3, hasta total_pages.
Por qué es útil: Las páginas se construyen por recuento de caracteres JSON, no por recuento de elementos, por lo que cada página cabe dentro de un tamaño fijo. Sin cursor ni estado del lado del servidor—solo números de página enteros.

🛠️ Opciones de instalación

📝 Requisitos previos generales

Instala uv (un instalador y resolutor de paquetes de Python rápido):
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Clona este repositorio y navega al directorio del proyecto:

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

🔌 Integración con clientes MCP

Una vez que tengas el LangSmith MCP Server, puedes integrarlo con varios clientes compatibles con MCP. Tienes dos opciones de instalación:

📦 Desde PyPI

Instala el paquete:

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

Añádelo a la configuración MCP de tu 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"
            }
        }
    }
}

⚙️ Desde el código fuente

Añade la siguiente configuración a los ajustes de tu cliente MCP (ejecuta desde la raíz del proyecto para que se encuentre el paquete):

{
    "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"
            }
        }
    }
}

Reemplaza los siguientes marcadores de posición:

/path/to/uv: La ruta absoluta a tu instalación de uv (p. ej., /Users/username/.local/bin/uv). Puedes encontrarla con which uv.
/path/to/langsmith-mcp-server: La ruta absoluta a la raíz del proyecto (el directorio que contiene pyproject.toml y langsmith_mcp_server/).
your_langsmith_api_key: Tu clave de API de LangSmith (obligatoria).
your_workspace_id: Tu ID de espacio de trabajo de LangSmith (opcional, para claves de API limitadas a múltiples espacios de trabajo).
https://api.smith.langchain.com: El endpoint de la API de LangSmith (opcional, por defecto usa el endpoint estándar).

Ejemplo de configuración (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"
            }
        }
    }
}

Copia esta configuración en Cursor → Configuración de MCP (reemplaza /path/to/uvx con la salida de which uvx).

LangSmith Cursor Integration

🔧 Encabezados (invocación de herramientas)

Al conectarse por HTTP (p. ej., HTTP streamable o un endpoint MCP alojado), el servidor usa encabezados para autenticación y configuración. Tu cliente MCP debe enviarlos con cada solicitud; no se requieren variables de entorno para la invocación de herramientas.

Encabezado	Obligatorio	Descripción
`LANGSMITH-API-KEY`	✅ Sí	Tu clave de API de LangSmith para llamadas de herramientas (listar prompts, obtener ejecuciones, etc.)
`LANGSMITH-WORKSPACE-ID`	❌ No	ID de espacio de trabajo para claves de API limitadas a múltiples espacios de trabajo
`LANGSMITH-ENDPOINT`	❌ No	URL de endpoint de API personalizado (para autoalojado o región UE)

Encabezados opcionales usados solo cuando la monitorización del servidor está habilitada (para agrupar trazas por sesión):

Encabezado	Descripción
`mcp-session-id`	ID de sesión o hilo; almacenado en los metadatos de la traza como `session_id`
`x-session-id`	Alternativa si `mcp-session-id` no está configurado
`x-request-id`	Alternativa para agrupación por ámbito de solicitud

Transporte Stdio: Al ejecutar el servidor por stdio (p. ej., uvx langsmith-mcp-server), no hay encabezados. El servidor recurre a las variables de entorno LANGSMITH_API_KEY, LANGSMITH_WORKSPACE_ID y LANGSMITH_ENDPOINT en el entorno del proceso para que la invocación de herramientas siga funcionando.

🔧 Variables de entorno

Las variables de entorno no se usan para la invocación de herramientas cuando se usa HTTP (se usan encabezados). Se usan para:

Transporte Stdio – alternativa para credenciales cuando no hay encabezados (ver arriba).
Pruebas de carga – p. ej., tests/load_test_sessions.py lee LANGSMITH_API_KEY del entorno (o de un archivo .env en la raíz del proyecto).
Monitorización opcional del servidor – rastreo de llamadas de herramientas a una segunda instancia de LangSmith (ver abajo).

Variable	Se usa para	Descripción
`LANGSMITH_API_KEY`	Alternativa Stdio, pruebas de carga	Clave de API de LangSmith (cuando no se proporciona mediante encabezados)
`LANGSMITH_WORKSPACE_ID`	Alternativa Stdio	ID de espacio de trabajo (opcional)
`LANGSMITH_ENDPOINT`	Alternativa Stdio	URL de endpoint personalizado (opcional)

Opcional: Monitorización de llamadas de herramientas a una segunda instancia de LangSmith

Puedes registrar cada llamada de herramienta MCP (con entradas y salidas) en un proyecto de LangSmith separado para monitorización y análisis. Configúralas en tu entorno (p. ej., en un archivo .env en la raíz del proyecto; el servidor carga .env mediante python-dotenv):

Variable	Obligatoria	Descripción
`LANGSMITH_MONITORING_API_KEY`	Sí (para habilitar)	Clave de API para la instancia de LangSmith usada para monitorización
`LANGSMITH_MONITORING_ENDPOINT`	No	URL del endpoint (predeterminado: nube)
`LANGSMITH_MONITORING_WORKSPACE_ID`	No	ID de espacio de trabajo para la instancia de monitorización
`LANGSMITH_MONITORING_PROJECT`	No	Nombre del proyecto para trazas de monitorización (predeterminado: `mcp-server-monitoring`)
`LANGSMITH_TRACING`	Sí (para enviar trazas)	Configúralo en `true` para que las trazas se envíen a LangSmith (instrumentación personalizada)

Cada ejecución de herramienta se rastrea con run_type="tool" y un session_id en los metadatos (del encabezado mcp-session-id, x-session-id o x-request-id cuando se usa HTTP, o generado por solicitud).

Si usas el LangSmith MCP Server alojado, se envían datos de uso anónimos a un proyecto de LangSmith separado para que podamos iterar y mejorar el producto.

🐳 Implementación con Docker (HTTP-Streamable)

El LangSmith MCP Server se puede implementar como un servidor HTTP usando Docker, lo que permite acceso remoto mediante el protocolo HTTP-streamable.

Construcción de la imagen Docker

docker build -t langsmith-mcp-server .

Ejecución con Docker

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

La clave de API se proporciona mediante el encabezado LANGSMITH-API-KEY al conectarse, por lo que no se requieren variables de entorno para el protocolo HTTP-streamable.

Conexión con el protocolo HTTP-Streamable

Una vez que el contenedor Docker esté en ejecución, puedes conectarte a él usando el transporte HTTP-streamable. El servidor acepta autenticación mediante encabezados:

Encabezado obligatorio:

LANGSMITH-API-KEY: Tu clave de API de LangSmith

Encabezados opcionales:

LANGSMITH-WORKSPACE-ID: ID de espacio de trabajo para claves de API limitadas a múltiples espacios de trabajo
LANGSMITH-ENDPOINT: URL de endpoint personalizado (para autoalojado o región UE)

Ejemplo de configuración de 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.

Integración con Cursor

Para añadir el LangSmith MCP Server a Cursor usando el protocolo HTTP-streamable, añade lo siguiente a tu archivo de configuración mcp.json:

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

Encabezados opcionales:

{
  "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"
      }
    }
  }
}

Asegúrate de que el servidor esté en ejecución antes de conectar Cursor a él.

Verificación de estado

El servidor proporciona un endpoint de verificación de estado:

curl http://localhost:8000/health

Este endpoint no requiere autenticación y devuelve "LangSmith MCP server is running" cuando el servidor está sano.

🧪 Desarrollo y contribuciones

Requisitos previos

Python 3.10+ (se recomienda 3.11+)
uv – instala con curl -LsSf https://astral.sh/uv/install.sh | sh
Clave de API de LangSmith – desde smith.langchain.com
Node.js (opcional) – solo si quieres usar MCP Inspector para probar el servidor (stdio o streamable-http)

Configuración

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)

Flujo de trabajo de desarrollo

Edita el código en langsmith_mcp_server/ o tests/.
Formato y lint (obligatorio antes de hacer commit):
```
make format
make lint
```

Ejecuta las pruebas:

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

Verificación de tipos (opcional): uv run mypy langsmith_mcp_server/

Pruebas con MCP Inspector

Puedes probar el servidor con MCP Inspector usando stdio o streamable-http.

Inicia MCP Inspector:
```
npx @modelcontextprotocol/inspector@latest
```
Abre http://localhost:6274 en tu navegador.
Conéctate en el Inspector:
- Stdio: Elige el transporte stdio y configura el comando del servidor (p. ej. uv run langsmith-mcp-server) y establece LANGSMITH_API_KEY en el entorno.
- Streamable HTTP: Inicia primero el servidor (uv run uvicorn langsmith_mcp_server.server:app --host 0.0.0.0 --port 8000 o Docker), luego elige streamable-http, URL http://localhost:8000/mcp, y añade la cabecera LANGSMITH-API-KEY = tu clave de API.

Pruebas de carga

Una prueba de carga basada en sesiones abre muchas sesiones MCP y llama a la herramienta list_prompts en cada una, usando langchain-mcp-adapters. Se ejecuta desde la CLI (sin interfaz gráfica). El servidor debe estar en ejecución primero.

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

Opciones

Opción	Predeterminado	Descripción
`--url`	`http://localhost:8000/mcp`	URL del endpoint MCP
`--api-key`	de `.env`	`LANGSMITH_API_KEY` (o configúralo en la raíz del proyecto `.env`)
`--sessions`	10	Número de sesiones concurrentes
`--calls-per-session`	3	llamadas `list_prompts` por sesión
`--debug`	off	Imprime registros paso a paso y el traceback del primer error
`--report` PATH	—	Escribe un informe después de la ejecución (ver más abajo)

Informe

Usa --report PATH para escribir un informe JSON después de la prueba (p. ej. --report load_test_report crea load_test_report.json con configuración, resumen, resultados por sesión y el primer error).

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

Lista de verificación para contribuciones

Antes de abrir un PR:

make format y make lint pasan
make test pasa
Las nuevas herramientas o comportamientos están documentados (p. ej. en CLAUDE.md si cambias la arquitectura o las herramientas)
El manejo de errores en las herramientas devuelve {"error": "..."} en lugar de lanzar una excepción

Para más detalles (añadir herramientas, estándares de código, solución de problemas), consulta CLAUDE.md.

📄 Licencia

Este proyecto se distribuye bajo la Licencia MIT. Para conocer los términos y condiciones detallados, consulta el archivo LICENSE.

Hecho con ❤️ por el equipo de LangChain