LangWatch MCP Server

The LangWatch MCP Server gives your AI coding assistant (Cursor, Claude Code, Codex, etc.) full access to all LangWatch and Scenario documentation and features via the Model Context Protocol.

Set up agent testing with Scenario to test agent behavior through user simulations and edge cases
Automatically instrument your code with LangWatch tracing for any framework (OpenAI, Agno, Mastra, DSPy, and more)
Set up evaluations to test and monitor your LLM outputs
Search and inspect traces from your LangWatch project directly in your editor
Query analytics to understand performance trends, costs, and error rates
Manage prompts: list, create, update, and version prompts without leaving your IDE

Instead of manually reading docs and writing boilerplate code, just ask your AI assistant to instrument your codebase with LangWatch, and it will do it for you.

The server URL is https://app.langwatch.ai/mcp. If you added LangWatch to your AI client before October 2026, update the connector’s URL to this one. Self-hosted deployments use their own host followed by /mcp.

Setup

Connect to the hosted server at https://app.langwatch.ai/mcp. Sign in with OAuth (recommended): your client opens a browser window, you sign in to LangWatch and approve a project, and the client refreshes its access on its own, with no key to manage. Clients that cannot sign in can send a personal API key as an Authorization: Bearer <key> header instead.

The Authorize MCP Connection page, asking to allow a client to use a LangWatch project — The approval page your client opens after you sign in: pick the project it may use, then Allow.

Go to Customize → Connectors, click + Add, then Add custom connector. On Team and Enterprise plans, an owner adds it under Organization settings → Connectors → Add → Custom → Web.
Enter the server URL: https://app.langwatch.ai/mcp
Click Connect: you’ll be redirected to sign in and approve access to a project

The same steps work in Claude Cowork and in Claude chat on the web.Requires a paid Claude plan.

Add the server, then sign in:

claude mcp add --transport http langwatch https://app.langwatch.ai/mcp

In Claude Code, run /mcp, pick langwatch and choose Authenticate. Sign in to LangWatch in the browser window that opens and approve a project.To use an API key instead of signing in, add the header when you add the server:

claude mcp add --transport http langwatch https://app.langwatch.ai/mcp --header "Authorization: Bearer your-api-key"

See the Claude Code MCP documentation for more details.

Add to .vscode/mcp.json in your project (or use MCP: Add Server from the Command Palette). Under the servers object, add an entry named langwatch with these fields:

type: http
url: https://app.langwatch.ai/mcp

VS Code opens a browser window to sign in the first time it connects. To use an API key instead, add headers.Authorization set to Bearer followed by your key.

Open Cursor Settings
Navigate to the Tools and MCP section in the sidebar
Add the LangWatch MCP server. Under the mcpServers object, add an entry named langwatch with the field url set to https://app.langwatch.ai/mcp

Cursor signs you in through your browser when it first connects. To use an API key instead, add headers.Authorization set to Bearer followed by your key.

Turn on developer mode, then add a custom MCP server in ChatGPT’s apps settings
Enter the server URL: https://app.langwatch.ai/mcp
Choose OAuth as the authentication
Click Connect: you’ll be redirected to sign in and approve access to a project

ChatGPT supports OAuth only, not API keys.

For any MCP client that supports remote servers:

Add a new remote MCP server with the URL https://app.langwatch.ai/mcp
Select OAuth authentication, or send a personal API key as an Authorization: Bearer <key> header
Connect, then sign in and approve a project in the browser window that opens

The server speaks the Streamable HTTP transport and supports OAuth Authorization Code + PKCE with Dynamic Client Registration, so any standards-compliant MCP client should work automatically.

Run it locally instead

Coding assistants can also run the MCP server on your machine with your API key and the project to work in. For Claude Code:

claude mcp add langwatch --env LANGWATCH_API_KEY=your-api-key-here --env LANGWATCH_PROJECT_ID=your-project-id -- npx -y @langwatch/mcp-server

For other editors, add an entry named langwatch under your editor’s MCP servers with these fields:

command: npx
args: -y, then the package name @langwatch/mcp-server on a separate token
env.LANGWATCH_API_KEY: your LangWatch API key
env.LANGWATCH_PROJECT_ID: your LangWatch project ID

This page intentionally describes the config in prose rather than as a JSON snippet. Some CLI agents (notably Gemini CLI 0.36.0 and earlier) parse @-prefixed runs as file paths and can crash with ENAMETOOLONG when a multi-line JSON snippet wraps the scoped package name in double quotes. See #3104 for details. The bash claude mcp add form above is safe: the package name is followed by a whitespace terminator.

Once connected, open your AI assistant’s chat and ask it to help with LangWatch tasks.

Local server configuration

Environment Variable	CLI Argument	Description
`LANGWATCH_API_KEY`	`--apiKey`	API key for authentication
`LANGWATCH_PROJECT_ID`	`--projectId`	The project to work in; needed for a personal API key, which can reach several projects
`LANGWATCH_ENDPOINT`	`--endpoint`	API endpoint (default: `https://app.langwatch.ai`)

Two Modes

The MCP server runs in two modes:

Remote (Streamable HTTP): Recommended, for every client. Hosted at https://app.langwatch.ai/mcp. Sign in with OAuth (Authorization Code + PKCE) in your browser and approve a project, or send a personal API key as a Bearer token.
Local (stdio): Runs as a subprocess of your coding assistant. API key set via --apiKey flag or LANGWATCH_API_KEY env var.

Usage Examples

Write Agent Tests with Scenario

Ask your AI assistant to write scenario tests for your agents:

"Write a scenario test that checks the agent calls the summarization tool when requested"

"Create a scenario test that verifies my agent handles error cases when the API is unavailable"

"Write scenario tests for my customer support agent covering refund requests and policy questions"

The AI assistant will:

Fetch the Scenario documentation and best practices
Create test files with proper imports and setup
Write scenario scripts that simulate user interactions
Add verification logic to check agent behavior
Include judge criteria to evaluate conversation quality

Example scenario test: Here’s an example scenario that checks for tool calls and includes criteria validation:

@pytest.mark.agent_test
@pytest.mark.asyncio
async def test_conversation_summary_request(agent_adapter):
    """Explicit summary requests should call the conversation summary tool."""

    def verify_summary_call(state: scenario.ScenarioState) -> bool:
        args = _require_tool_call(state, "get_conversation_summary")
        assert "conversation_context" in args, "summary tool must include context reference"
        return True

    result = await scenario.run(
        name="conversation summary follow-up",
        description="Customer wants a recap of troubleshooting steps that were discussed.",
        agents=[
            agent_adapter,
            scenario.UserSimulatorAgent(),
            scenario.JudgeAgent(
                criteria=[
                    "Agent provides a clear recap",
                    "Agent confirms next steps and resources",
                ]
            ),
        ],
        script=[
            scenario.user("Thanks for explaining the dispute process earlier."),
            scenario.agent(),
            scenario.user(
                "Before we wrap, can you summarize everything we covered so I don't miss a step?"
            ),
            scenario.agent(),
            verify_summary_call,
            scenario.judge(),
        ],
    )

    assert result.success, result.reasoning

The LangWatch MCP automatically handles fetching the right documentation, understanding your agent’s framework, and generating tests that follow Scenario best practices.

Instrument Your Code with LangWatch

Ask your AI assistant to add LangWatch tracking to your existing code:

"Please instrument my code with LangWatch"

"Add LangWatch tracing to my OpenAI chatbot with RAG tracking for the vector search"

"Instrument this LangChain agent with LangWatch, including all tool calls"

The AI assistant will:

Fetch the relevant LangWatch documentation for your framework
Add the necessary imports and setup code
Wrap your functions with @langwatch.trace() decorators
Configure automatic tracking for your LLM calls
Add labels and metadata following best practices

Example transformation: Before:

from openai import OpenAI

client = OpenAI()

def chat(message: str):
    response = client.chat.completions.create(
        model="gpt-6-luna",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

import { OpenAI } from "openai";

const client = new OpenAI();

async function chat(message: string) {
  const response = await client.chat.completions.create({
    model: "gpt-5-mini",
    messages: [{ role: "user", content: message }],
  });
  return response.choices[0].message.content;
}

After (automatically added by AI assistant):

from openai import OpenAI
import langwatch

client = OpenAI()
langwatch.setup()

@langwatch.trace()
def chat(message: str):
    langwatch.get_current_trace().autotrack_openai_calls(client)
    langwatch.get_current_trace().update(
        metadata={"labels": ["document_parsing"]}
    )

    response = client.chat.completions.create(
        model="gpt-6-luna",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

import { OpenAI } from "openai";
import { setupObservability } from "langwatch/observability/node";
import { getLangWatchTracer } from "langwatch/observability";

setupObservability({ serviceName: "chatbot" });
const tracer = getLangWatchTracer("chatbot");
const client = new OpenAI();

async function chat(message: string) {
  return tracer.withActiveSpan("chat", async (span) => {
    span.setInput(message);
    span.setAttribute("langwatch.labels", ["document_parsing"]);
    const response = await client.chat.completions.create({
      model: "gpt-5-mini",
      messages: [{ role: "user", content: message }],
    });
    const text = response.choices[0].message.content;
    span.setOutput(text);
    return text;
  });
}

Set Up Evaluations

Ask your AI assistant to set up evaluation code for your LLM outputs:

"Create a notebook to evaluate the faithfulness of my RAG pipeline using LangWatch's Evaluating via Code guide"

The AI assistant will:

Fetch the relevant LangWatch evaluation documentation
Create evaluation notebooks or scripts with proper setup
Add evaluation metrics and criteria for your use case
Include code to run evaluations following Evaluating via Code

Search and Debug Traces

Ask your AI assistant to find and analyze traces from your project:

"Search for traces with errors in the last 24 hours"

"Get the full details of trace abc123 and explain what happened"

"Find all traces for thread thread_xyz and show me the full conversation flow"

The AI assistant will use search_traces to find matching traces and get_trace to drill into individual ones. Traces are returned as AI-readable digests by default, showing the full span hierarchy with timing, inputs, outputs, and errors.

Query Analytics

Ask about performance trends, costs, and usage patterns:

"Show me the total LLM cost for the last 7 days"

"What's the p95 completion time for the last 30 days, broken down by model?"

"How many traces have we had per day this week?"

The assistant starts with discover_schema to understand available metrics and filters, then uses get_analytics to query timeseries data.

Manage Prompts

Ask your AI assistant to work with prompts:

"List all prompts in my LangWatch project"

"Create a new prompt called 'pdf-parser' with a system message for extracting structured data from PDFs"

"Update the pdf-parser prompt to also handle images, and create a new version"

The AI assistant will guide you through creating, versioning, and using prompts from LangWatch’s Prompt Management.

Advanced: Self-Building AI Agents

An AI agent can use the LangWatch MCP to instrument itself while it is being built, which lets it track and debug its own behavior.

MCP Tools Reference

The MCP server provides tools organized into categories. Your AI assistant automatically chooses the right tools based on your request.

Documentation and Support

Tool	Description
`fetch_langwatch_docs`	Fetch LangWatch integration docs
`fetch_scenario_docs`	Fetch Scenario agent testing docs
`report_issue`	Report anything that did not work to the LangWatch team (no API key needed, user permission required, secrets redacted locally). See the reporting guide

Observability (requires API key)

Tool	Description
`discover_schema`	Explore available filter fields, metrics, aggregation types, and group-by options
`search_traces`	Search traces with filters, text query, and date range. Returns AI-readable digests by default
`get_trace`	Get full trace details by ID with span hierarchy, evaluations, and metadata
`get_analytics`	Query timeseries analytics (costs, latency, token usage, etc.)

Prompts (requires API key)

Tool	Description
`platform_list_prompts`	List all prompts in the project
`platform_get_prompt`	Get a prompt with messages, model config, and version history
`platform_create_prompt`	Create a new prompt with messages and model configuration
`platform_update_prompt`	Update a prompt or create a new version

Evaluations (requires API key)

Tool	Description
`platform_list_evaluators`	List the saved evaluators in the project
`platform_get_evaluator`	Get a saved evaluator with its type, settings and input mappings
`platform_create_evaluator`	Create a saved evaluator
`platform_update_evaluator`	Update a saved evaluator’s settings or mappings
`platform_delete_evaluator`	Delete a saved evaluator
`platform_list_monitors`	List the online evaluations
`platform_get_monitor`	Get an online evaluation with its evaluator, preconditions and sampling
`platform_create_monitor`	Create an online evaluation
`platform_update_monitor`	Update, enable or disable an online evaluation
`platform_delete_monitor`	Delete an online evaluation
`platform_experiment_list`	List the experiments in the project
`platform_run_experiment`	Start an experiment run, optionally with a `concurrency` from 1 to 24: the cells that run at once, for that run only
`platform_experiment_status`	Get the progress of a run
`platform_experiment_list_runs`	List the runs of an experiment
`platform_experiment_results`	Get the per-row results of a run

Dataset tools are listed on the datasets page. Annotation tools are platform_list_annotations, platform_get_annotation, platform_create_annotation and platform_delete_annotation.

Organization Management (requires org-level API key)

Tool	Description
`platform_list_projects`	List all projects in the organization
`platform_get_project`	Get project details by ID
`platform_create_project`	Create a new project (returns a one-time service API key)
`platform_update_project`	Update a project’s name, language, framework, or PII settings
`platform_archive_project`	Archive a project (soft-delete)
`platform_list_api_keys`	List all API keys in the organization
`platform_create_api_key`	Create a personal or service API key
`platform_revoke_api_key`	Revoke an API key

Organization management tools require an API key with org-level permissions. If the configured key lacks organization permissions, these tools will return a clear error message.

Tool Details

`discover_schema`

Discover available filter fields, metrics, aggregation types, and group-by options for LangWatch queries. Call this before using search_traces or get_analytics to understand available options. Parameters:

category (required): One of "filters", "metrics", "aggregations", "groups", or "all"

`search_traces`

Search traces with filters, text query, and date range. Returns AI-readable trace digests by default. Parameters:

query (optional): Text search query
startDate (optional): Start date, ISO string or relative like "24h", "7d", "30d". Default: 24h ago
endDate (optional): End date, ISO string or relative. Default: now
filters (optional): Filter object (e.g. {"metadata.labels": ["production"]})
pageSize (optional): Results per page (default: 25, max: 1000)
scrollId (optional): Pagination token from previous search
format (optional): "digest" (default, AI-readable) or "json" (full raw data)

`get_trace`

Get full details of a single trace by ID. Returns AI-readable trace digest by default. Parameters:

traceId (required): The trace ID to retrieve
format (optional): "digest" (default, AI-readable) or "json" (full raw data)

`get_analytics`

Query analytics timeseries from LangWatch. Metrics use "category.name" format (e.g., "performance.completion_time"). Parameters:

metric (required): Metric in "category.name" format (e.g., "metadata.trace_id", "performance.total_cost")
aggregation (optional): avg, sum, min, max, median, p90, p95, p99, cardinality, terms. Default: avg
startDate (optional): Start date, ISO string or relative. Default: 7 days ago
endDate (optional): End date. Default: now
groupBy (optional): Group results by field
filters (optional): Filters to apply
timeZone (optional): Timezone. Default: UTC

`platform_list_prompts`

List all prompts configured in the LangWatch project. No parameters required.

`platform_get_prompt`

Get a specific prompt by ID or handle, including messages, model config, and version history. Parameters:

idOrHandle (required): Prompt ID or handle
version (optional): Specific version number (default: latest)

`platform_create_prompt`

Create a new prompt in the LangWatch project. Parameters:

name (required): Prompt name
messages (required): Array of {role, content} messages
model (required): Model name (e.g., "gpt-6-luna", "claude-sonnet-4-5-20250929")
modelProvider (required): Provider name (e.g., "openai", "anthropic")
handle (optional): URL-friendly handle
description (optional): Prompt description

`platform_update_prompt`

Update an existing prompt or create a new version. Parameters:

idOrHandle (required): Prompt ID or handle to update
messages (optional): Updated messages array
model (optional): Updated model name
modelProvider (optional): Updated provider
createVersion (optional): If true, creates a new version instead of updating in place
commitMessage (optional): Commit message for the change

`fetch_langwatch_docs`

Fetches LangWatch documentation pages to understand how to implement features. Parameters:

url (optional): The full URL of a specific doc page. If not provided, fetches the docs index.

`fetch_scenario_docs`

Fetches Scenario documentation pages to understand how to write agent tests. Parameters:

url (optional): The full URL of a specific doc page. If not provided, fetches the docs index.

Your AI assistant will automatically choose the right tools based on your request. You don’t need to call these tools manually.

Found broken or outdated docs? Use Report outdated or broken docs next to Edit this page below. Agents: include the page URL, the failing step and a proposed fix in a GitHub issue. For CLI diagnostics, ask your user before running npx langwatch report --user-approved. See the reporting guide.

Get Started

Agent Testing

Observability

Evaluations

Prompt Management

Platform

Examples & Cookbooks

Help

LangWatch MCP Server

Setup

Run it locally instead

Local server configuration

Two Modes

Usage Examples

Write Agent Tests with Scenario

Instrument Your Code with LangWatch

Set Up Evaluations

Search and Debug Traces

Query Analytics

Manage Prompts

Advanced: Self-Building AI Agents

MCP Tools Reference

Documentation and Support

Observability (requires API key)

Prompts (requires API key)

Evaluations (requires API key)

Organization Management (requires org-level API key)

Tool Details

`discover_schema`

`search_traces`

`get_trace`

`get_analytics`

`platform_list_prompts`

`platform_get_prompt`

`platform_create_prompt`

`platform_update_prompt`

`fetch_langwatch_docs`

`fetch_scenario_docs`

​Setup

​Run it locally instead

​Local server configuration

​Two Modes

​Usage Examples

​Write Agent Tests with Scenario

​Instrument Your Code with LangWatch

​Set Up Evaluations

​Search and Debug Traces

​Query Analytics

​Manage Prompts

​Advanced: Self-Building AI Agents

​MCP Tools Reference

​Documentation and Support

​Observability (requires API key)

​Prompts (requires API key)

​Evaluations (requires API key)

​Organization Management (requires org-level API key)

​Tool Details

​discover_schema

​search_traces

​get_trace

​get_analytics

​platform_list_prompts

​platform_get_prompt

​platform_create_prompt

​platform_update_prompt

​fetch_langwatch_docs

​fetch_scenario_docs

Setup

Run it locally instead

Local server configuration

Two Modes

Usage Examples

Write Agent Tests with Scenario

Instrument Your Code with LangWatch

Set Up Evaluations

Search and Debug Traces

Query Analytics

Manage Prompts

Advanced: Self-Building AI Agents

MCP Tools Reference

Documentation and Support

Observability (requires API key)

Prompts (requires API key)

Evaluations (requires API key)

Organization Management (requires org-level API key)

Tool Details

`discover_schema`

`search_traces`

`get_trace`

`get_analytics`

`platform_list_prompts`

`platform_get_prompt`

`platform_create_prompt`

`platform_update_prompt`

`fetch_langwatch_docs`

`fetch_scenario_docs`