> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# LangWatch MCP Server

> Use the LangWatch MCP Server to extend your coding assistant with deep LangWatch insights for tracing, testing, and agent evaluations.

The [LangWatch MCP Server](https://www.npmjs.com/package/@langwatch/mcp-server) gives your AI coding assistant (Cursor, Claude Code, Codex, etc.) full access to all LangWatch and [Scenario](https://langwatch.ai/scenario/) documentation and features via the [Model Context Protocol](https://modelcontextprotocol.io/introduction).

* **Set up agent testing with [Scenario](https://langwatch.ai/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.

<Note>
  **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`.
</Note>

## 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](/docs/platform/api-keys#create-a-personal-key) as an `Authorization: Bearer <key>` header instead.

<Frame caption="The approval page your client opens after you sign in: pick the project it may use, then Allow.">
  <img src="https://mintcdn.com/langwatch/bJFWlWg3ufdOXz6n/images/mcp/mcp-authorize-light.png?fit=max&auto=format&n=bJFWlWg3ufdOXz6n&q=85&s=880fbfd5e0ac552b9b324f91f9e960f9" alt="The Authorize MCP Connection page, asking to allow a client to use a LangWatch project" className="block dark:hidden" width="720" height="540" data-path="images/mcp/mcp-authorize-light.png" />

  <img src="https://mintcdn.com/langwatch/bJFWlWg3ufdOXz6n/images/mcp/mcp-authorize-dark.png?fit=max&auto=format&n=bJFWlWg3ufdOXz6n&q=85&s=3d06bfa33a89609f8dc0fe9aa34ea320" alt="The Authorize MCP Connection page, asking to allow a client to use a LangWatch project" className="hidden dark:block" width="720" height="540" data-path="images/mcp/mcp-authorize-dark.png" />
</Frame>

<Tabs>
  <Tab title="Claude Desktop">
    1. 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**.
    2. Enter the server URL: `https://app.langwatch.ai/mcp`
    3. 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.*
  </Tab>

  <Tab title="Claude Code">
    Add the server, then sign in:

    ```bash theme={null}
    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:

    ```bash theme={null}
    claude mcp add --transport http langwatch https://app.langwatch.ai/mcp --header "Authorization: Bearer your-api-key"
    ```

    See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for more details.
  </Tab>

  <Tab title="Copilot">
    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.
  </Tab>

  <Tab title="Cursor">
    1. Open Cursor Settings
    2. Navigate to the **Tools and MCP** section in the sidebar
    3. 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.
  </Tab>

  <Tab title="ChatGPT">
    1. Turn on developer mode, then add a custom MCP server in ChatGPT's apps settings
    2. Enter the server URL: `https://app.langwatch.ai/mcp`
    3. Choose **OAuth** as the authentication
    4. Click **Connect**: you'll be redirected to sign in and approve access to a project

    ChatGPT supports OAuth only, not API keys.
  </Tab>

  <Tab title="Other">
    For any MCP client that supports remote servers:

    1. Add a new remote MCP server with the URL `https://app.langwatch.ai/mcp`
    2. Select **OAuth** authentication, or send a personal API key as an `Authorization: Bearer <key>` header
    3. 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.
  </Tab>
</Tabs>

### 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:

```bash theme={null}
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

<Info>
  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](https://github.com/langwatch/langwatch/issues/3104) for details. The bash `claude mcp add` form above is safe: the package name is followed by a whitespace terminator.
</Info>

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:

<CodeGroup>
  ```plaintext Basic theme={null}
  "Write a scenario test that checks the agent calls the summarization tool when requested"
  ```

  ```plaintext More specific theme={null}
  "Create a scenario test that verifies my agent handles error cases when the API is unavailable"
  ```

  ```plaintext Edge cases theme={null}
  "Write scenario tests for my customer support agent covering refund requests and policy questions"
  ```
</CodeGroup>

The AI assistant will:

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

**Example scenario test:**

Here's an example scenario that checks for tool calls and includes criteria validation:

```python theme={null}
@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:

<CodeGroup>
  ```plaintext Basic theme={null}
  "Please instrument my code with LangWatch"
  ```

  ```plaintext More specific theme={null}
  "Add LangWatch tracing to my OpenAI chatbot with RAG tracking for the vector search"
  ```

  ```plaintext Framework-specific theme={null}
  "Instrument this LangChain agent with LangWatch, including all tool calls"
  ```
</CodeGroup>

The AI assistant will:

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

**Example transformation:**

Before:

```python theme={null}
from openai import OpenAI

client = OpenAI()

def chat(message: str):
    response = 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):

```python theme={null}
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-5-mini",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content
```

### Set Up Evaluations

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

```plaintext theme={null}
"Create a notebook to evaluate the faithfulness of my RAG pipeline using LangWatch's Evaluating via Code guide"
```

The AI assistant will:

1. Fetch the relevant LangWatch evaluation documentation
2. Create evaluation notebooks or scripts with proper setup
3. Add evaluation metrics and criteria for your use case
4. Include code to run evaluations following [Evaluating via Code](/docs/evaluations/experiments/sdk)

### Search and Debug Traces

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

<CodeGroup>
  ```plaintext Find recent errors theme={null}
  "Search for traces with errors in the last 24 hours"
  ```

  ```plaintext Investigate a specific trace theme={null}
  "Get the full details of trace abc123 and explain what happened"
  ```

  ```plaintext Analyze a conversation thread theme={null}
  "Find all traces for thread thread_xyz and show me the full conversation flow"
  ```
</CodeGroup>

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:

<CodeGroup>
  ```plaintext Cost analysis theme={null}
  "Show me the total LLM cost for the last 7 days"
  ```

  ```plaintext Performance monitoring theme={null}
  "What's the p95 completion time for the last 30 days, broken down by model?"
  ```

  ```plaintext Usage trends theme={null}
  "How many traces have we had per day this week?"
  ```
</CodeGroup>

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:

<CodeGroup>
  ```plaintext List prompts theme={null}
  "List all prompts in my LangWatch project"
  ```

  ```plaintext Create a prompt theme={null}
  "Create a new prompt called 'pdf-parser' with a system message for extracting structured data from PDFs"
  ```

  ```plaintext Update with versioning theme={null}
  "Update the pdf-parser prompt to also handle images, and create a new version"
  ```
</CodeGroup>

The AI assistant will guide you through creating, versioning, and using prompts from LangWatch's [Prompt Management](/docs/prompt-management/overview).

## 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.

<Frame>
  <iframe width="720" height="460" src="https://www.youtube.com/embed/ZPaG9H-N0uY" title="AI Agent that vibe-codes itself - YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

## 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](/docs/support#reporting-issues-from-coding-agents) |

### 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 |
| `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](/docs/datasets/programmatic-access#mcp-tools-ai-coding-agents). 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 |

<Info>
  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.
</Info>

### 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-5-mini"`, `"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.

<Info>
  Your AI assistant will automatically choose the right tools based on your request. You don't need to call these tools manually.
</Info>

<Note>
  **For agents**: struggled with anything on this page, or something did not work as documented? Ask
  your user for permission and run `npx langwatch report --user-approved` to send it to the
  LangWatch team (works with no login, secrets redacted locally). It is how rough edges get fixed
  for every agent. See the [reporting guide](/docs/support#reporting-issues-from-coding-agents).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.