@langwatch/mcp-server 0.10.1 → 2.0.0

package/.python-version

@@ -0,0 +1 @@
+3.11

package/.release-please-shim

@@ -1 +1 @@
-release-please shadow marker (v2) — next: 0.8.0
+release-please shadow marker (v3), next: 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [2.0.0](https://github.com/langwatch/langwatch/compare/mcp-server@v1.0.0...mcp-server@v2.0.0) (2026-08-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* **mcp-server:** three behaviors change for callers of the HTTP server. A client that authenticated once at initialize and then sent only the session id must now send Authorization: Bearer <key> on every request. GET /sse?apiKey=<key> no longer authenticates; use the Authorization header. A deployment relying on the implicit 0.0.0.0 bind must pass --host 0.0.0.0, which the published container image already does.
+
+### Features
+
+* **api-docs:** publish the REST API the SDKs actually call, and gate route coverage ([#6605](https://github.com/langwatch/langwatch/issues/6605)) ([25884bf](https://github.com/langwatch/langwatch/commit/25884bf3992eb99c00c3c7bafb09b979b02f0013))
+
+
+### Bug Fixes
+
+* **mcp-server:** authorize every request to the standalone HTTP server ([#6641](https://github.com/langwatch/langwatch/issues/6641)) ([af324de](https://github.com/langwatch/langwatch/commit/af324deeb3700f2745783a46e6fd5e8625ef868e))
+
+
+### Code Refactoring
+
+* **build:** single pnpm workspace + restructure into sdks/ platform/ services/ mcp/ infra/ (ADR-076) ([#6405](https://github.com/langwatch/langwatch/issues/6405)) ([2bbeb7d](https://github.com/langwatch/langwatch/commit/2bbeb7dd2e0747e81478f22c3165adb9163c9f99))
+
+## [1.0.0](https://github.com/langwatch/langwatch/compare/mcp-server@v0.10.1...mcp-server@v1.0.0) (2026-07-24)
+
+
+### Features
+
+* agent issue reports, npx langwatch report at every access point ([#6101](https://github.com/langwatch/langwatch/issues/6101)) ([e881f8e](https://github.com/langwatch/langwatch/commit/e881f8e5ed5e24094e9c55e3f8d390c9ff2f43e4))
+* **errors:** handled-error remediation channel (tips/docsUrl/fault) + shared package ([#5917](https://github.com/langwatch/langwatch/issues/5917)) ([bf9bf5a](https://github.com/langwatch/langwatch/commit/bf9bf5ab61c1c70160be712532a92d81816f77be))
+* **langy:** event-sourced frontend, model-emitted cards, and a home built on one field ([#6027](https://github.com/langwatch/langwatch/issues/6027)) ([5d72c7e](https://github.com/langwatch/langwatch/commit/5d72c7efc7b27fbc683ed77df7a943d01fb6b7a9))
+* **mcp-server:** graduate to 1.0.0 ([fa2341f](https://github.com/langwatch/langwatch/commit/fa2341f3e4e2caafea684886e3f68de99c5e9bd4))
+
+
+### Bug Fixes
+
+* **deps:** bump @anthropic-ai/claude-code to 2.1.202 with consistent lockfiles ([#5808](https://github.com/langwatch/langwatch/issues/5808)) ([a32cb2d](https://github.com/langwatch/langwatch/commit/a32cb2d7935dab244e05dd6ef360296d90a548d5))
+* **mcp-server:** bump vitest to 4.1.8 for SNYK-JS-VITEST-17375131 ([#5379](https://github.com/langwatch/langwatch/issues/5379)) ([f495f35](https://github.com/langwatch/langwatch/commit/f495f35e385db610bdfbd235992dbcf18df8b1eb))
+* **mcp-server:** keep zod and @modelcontextprotocol/sdk as real dependencies ([#5976](https://github.com/langwatch/langwatch/issues/5976)) ([2a368ef](https://github.com/langwatch/langwatch/commit/2a368eff7f7b1129b992bf3a74259e63cf299140))
+* **mcp-server:** move unused runtime deps to devDependencies (npx cold-start 27s -&gt; 2s) ([#5965](https://github.com/langwatch/langwatch/issues/5965)) ([7c5b49a](https://github.com/langwatch/langwatch/commit/7c5b49a18cc24a1c9f0a462d521c5907e4e98216))
+* **mcp-server:** surface evaluation results in search_traces ([#5983](https://github.com/langwatch/langwatch/issues/5983)) ([dacb1e9](https://github.com/langwatch/langwatch/commit/dacb1e9fbadfb0d156bf44d31cd263720180eded))
+* **security:** harden MCP outbound requests and browser policy ([#6091](https://github.com/langwatch/langwatch/issues/6091)) ([694aeaf](https://github.com/langwatch/langwatch/commit/694aeaf21e8aab41055d027c6106c64d8e67e624))
+* **security:** raise hono and undici floors across npm workspaces ([#5071](https://github.com/langwatch/langwatch/issues/5071)) ([5b5d57a](https://github.com/langwatch/langwatch/commit/5b5d57ac59baa38e90f9db82f3c213a26262bce4))
+* **security:** raise litellm to &gt;=1.84.0 in mcp-server and python-sdk ([cb44747](https://github.com/langwatch/langwatch/commit/cb447477d21feb9448445505bbe088f4b54776dc))
+* **security:** raise litellm to &gt;=1.84.0 in mcp-server and python-sdk (CRITICAL) ([#5230](https://github.com/langwatch/langwatch/issues/5230)) ([cb44747](https://github.com/langwatch/langwatch/commit/cb447477d21feb9448445505bbe088f4b54776dc))
+* **security:** raise mcp-server python-dotenv and python-liquid transitive floors ([#5610](https://github.com/langwatch/langwatch/issues/5610)) ([52db5a4](https://github.com/langwatch/langwatch/commit/52db5a4c69e7a6b7bef9d80cf58d696d44ce4238))
+
+
+### Miscellaneous
+
+* **deps-dev:** bump @anthropic-ai/claude-code ([acb7ce4](https://github.com/langwatch/langwatch/commit/acb7ce41ac1ec574ed8b1a78aeddd4867246ee5c))
+* **deps-dev:** bump @anthropic-ai/claude-code from 2.1.158 to 2.1.163 in /mcp-server in the npm_and_yarn group across 1 directory ([#4995](https://github.com/langwatch/langwatch/issues/4995)) ([acb7ce4](https://github.com/langwatch/langwatch/commit/acb7ce41ac1ec574ed8b1a78aeddd4867246ee5c))
+* **deps-dev:** bump @anthropic-ai/claude-code from 2.1.163 to 2.1.195 in /mcp-server ([#5376](https://github.com/langwatch/langwatch/issues/5376)) ([5ff4826](https://github.com/langwatch/langwatch/commit/5ff4826214587a6aed784a69578062ab12fd9df1))
+* **deps-dev:** bump @anthropic-ai/claude-code in /mcp-server ([5ff4826](https://github.com/langwatch/langwatch/commit/5ff4826214587a6aed784a69578062ab12fd9df1))
+* **deps-dev:** bump @langwatch/scenario from 0.4.11 to 0.4.15 in /mcp-server ([#5338](https://github.com/langwatch/langwatch/issues/5338)) ([de74e61](https://github.com/langwatch/langwatch/commit/de74e6183244683b650105eea70dda5fe4bda4a4))
+* **deps-dev:** bump @langwatch/scenario in /mcp-server ([de74e61](https://github.com/langwatch/langwatch/commit/de74e6183244683b650105eea70dda5fe4bda4a4))
+* **deps-dev:** bump @types/eslint__js from 8.42.3 to 9.14.0 in /langwatch ([#4605](https://github.com/langwatch/langwatch/issues/4605)) ([b937610](https://github.com/langwatch/langwatch/commit/b937610ea11752f5a07aa111da07e9dd7bbaa9f8))
+* **deps-dev:** bump @typescript/native-preview from 7.0.0-dev.20250911.1 to 7.0.0-dev.20260628.1 in /mcp-server ([#5373](https://github.com/langwatch/langwatch/issues/5373)) ([1ac876f](https://github.com/langwatch/langwatch/commit/1ac876fe55f2c73452c82b9a4219e52980dda9d2))
+* **deps-dev:** bump @typescript/native-preview to 7.0.0-dev.20260628.1 in /mcp-server ([1ac876f](https://github.com/langwatch/langwatch/commit/1ac876fe55f2c73452c82b9a4219e52980dda9d2))
+* **deps-dev:** bump eslint from 10.4.1 to 10.6.0 in /mcp-server ([#5372](https://github.com/langwatch/langwatch/issues/5372)) ([78244c1](https://github.com/langwatch/langwatch/commit/78244c197c8000cb7358f19f7cdcf7e07e93231e))
+* **deps-dev:** bump the typescript-native-preview group across 3 directories with 1 update ([#5721](https://github.com/langwatch/langwatch/issues/5721)) ([6e44614](https://github.com/langwatch/langwatch/commit/6e44614f5b193cf959203bb32e357cc7407e4b16))
+* **deps-dev:** bump the typescript-native-preview group across 3 directories with 1 update ([#5755](https://github.com/langwatch/langwatch/issues/5755)) ([1508d35](https://github.com/langwatch/langwatch/commit/1508d359e5bc5a8f382dbec25d53c5448b910d90))
+* **deps-dev:** bump tsx from 4.22.3 to 4.22.4 in /mcp-server ([#4779](https://github.com/langwatch/langwatch/issues/4779)) ([1e8e538](https://github.com/langwatch/langwatch/commit/1e8e538e57e0096957439a4146a5eea480df3e93))
+* **deps-dev:** bump typescript-eslint from 8.60.0 to 8.62.0 in /mcp-server ([#4880](https://github.com/langwatch/langwatch/issues/4880)) ([5773c2d](https://github.com/langwatch/langwatch/commit/5773c2db77634313075eb58e94190e0d7c146577))
+* **deps-dev:** bump typescript-eslint from 8.62.0 to 8.62.1 in /mcp-server ([#5478](https://github.com/langwatch/langwatch/issues/5478)) ([9250768](https://github.com/langwatch/langwatch/commit/92507686d7d519691b8d53a625c4a67374ded313))
+* **deps-dev:** bump typescript-eslint in /mcp-server ([9250768](https://github.com/langwatch/langwatch/commit/92507686d7d519691b8d53a625c4a67374ded313))
+* **deps-dev:** bump typescript-eslint in /mcp-server ([5773c2d](https://github.com/langwatch/langwatch/commit/5773c2db77634313075eb58e94190e0d7c146577))
+* **deps-dev:** remove redundant @types/eslint__js in /mcp-server ([b937610](https://github.com/langwatch/langwatch/commit/b937610ea11752f5a07aa111da07e9dd7bbaa9f8))
+* **deps:** batch small dependency updates in /langwatch + /mcp-server ([#5447](https://github.com/langwatch/langwatch/issues/5447)) ([daed7b1](https://github.com/langwatch/langwatch/commit/daed7b1325fc06b70c0739849d27280a8a4f6c9c))
+* **deps:** bump @modelcontextprotocol/sdk from 1.26.0 to 1.29.0 in /langwatch ([#4607](https://github.com/langwatch/langwatch/issues/4607)) ([08f2ce6](https://github.com/langwatch/langwatch/commit/08f2ce6b50877edf35ec524e1524afdbb5de53b0))
+* **deps:** bump @opentelemetry/context-async-hooks from 2.7.1 to 2.8.0 in /mcp-server ([#5033](https://github.com/langwatch/langwatch/issues/5033)) ([1506b70](https://github.com/langwatch/langwatch/commit/1506b701e999bc779190bff988942927537cffd1))
+* **deps:** bump @opentelemetry/context-async-hooks in /mcp-server ([1506b70](https://github.com/langwatch/langwatch/commit/1506b701e999bc779190bff988942927537cffd1))
+* **deps:** bump @opentelemetry/sdk-node from 0.217.0 to 0.219.0 in /mcp-server ([#5048](https://github.com/langwatch/langwatch/issues/5048)) ([9f1ef55](https://github.com/langwatch/langwatch/commit/9f1ef5572a9cca3114e583b4a319fb3ec416e080))
+* **deps:** bump @opentelemetry/sdk-node in /mcp-server ([9f1ef55](https://github.com/langwatch/langwatch/commit/9f1ef5572a9cca3114e583b4a319fb3ec416e080))
+* **deps:** bump vitest from 4.1.0 to 4.1.9 in /mcp-server ([#4784](https://github.com/langwatch/langwatch/issues/4784)) ([efe348f](https://github.com/langwatch/langwatch/commit/efe348f4b4e4836f7b27d5ab32673a5bc77323a2))
+* **deps:** bump yargs from 17.7.2 to 18.0.0 in /mcp-server ([#4307](https://github.com/langwatch/langwatch/issues/4307)) ([dddc31d](https://github.com/langwatch/langwatch/commit/dddc31d6901a4d7fc91ea25fe442810dacdbda67))
+
 ## [0.10.1](https://github.com/langwatch/langwatch/compare/mcp-server@v0.10.0...mcp-server@v0.10.1) (2026-05-31)
 
 

package/CONTRIBUTING.md

@@ -15,7 +15,7 @@ Thank you for your interest in contributing to the LangWatch MCP Server! This gu
 1. **Clone the repository and navigate to the MCP server directory:**
    ```bash
    git clone https://github.com/langwatch/langwatch.git
-   cd langwatch/mcp-server
+   cd langwatch/mcp/typescript
    ```
 
 2. **Install dependencies and build the MCP server:**

package/README.md

@@ -4,29 +4,21 @@ MCP server that gives AI coding agents access to LangWatch observability data, p
 
 ## Quick Setup
 
-Add to your MCP client configuration (Claude Code, Cursor, etc.):
-
-```json
-{
-  "mcpServers": {
-    "langwatch": {
-      "command": "npx",
-      "args": ["-y", "@langwatch/mcp-server"],
-      "env": {
-        "LANGWATCH_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
-```
-
-For Claude Code, you can also run:
+For Claude Code, run:
 
 ```bash
 claude mcp add langwatch -- npx -y @langwatch/mcp-server --apiKey your-api-key-here
 ```
 
-The API key is required for observability and prompt tools. Documentation tools work without it.
+For Claude Code (manual) or other MCP clients (Cursor, Copilot, etc.), add an entry named `langwatch` under the `mcpServers` object of your client's MCP settings file 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
+
+In stdio mode the API key is required for observability and prompt tools, and documentation tools work without it. In HTTP mode every MCP request needs a valid key, including documentation-tool requests, because the server authenticates the request before it reaches any tool.
+
+> The config is described in prose rather than as a JSON snippet because 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). The bash form above is safe — the package name is followed by a whitespace terminator.
 
 ## Configuration
 
@@ -34,6 +26,60 @@ The API key is required for observability and prompt tools. Documentation tools
 |---------|---------|-------------|
 | `LANGWATCH_API_KEY` | `--apiKey` | API key for authentication |
 | `LANGWATCH_ENDPOINT` | `--endpoint` | API endpoint (default: `https://app.langwatch.ai`) |
+| | `--http` | Serve over HTTP and SSE instead of stdio |
+| | `--port` | HTTP port (default: `3000`) |
+| `LANGWATCH_MCP_HTTP_HOST` | `--host` | HTTP listen address (default: `127.0.0.1`) |
+| `LANGWATCH_MCP_ALLOWED_ORIGINS` | `--allowedOrigin` | Browser origins allowed to call the HTTP server |
+| `LANGWATCH_MCP_TRUST_PROXY` | | Use `X-Forwarded-For` as the rate limit key (default: off) |
+
+### HTTP mode
+
+In HTTP mode each client brings its own API key in an `Authorization: Bearer <key>`
+header, on every MCP request rather than only at session start. That covers
+`/mcp`, `/sse`, and `/messages`. The key is checked against the LangWatch API
+before a session is created and re-checked on each request, so a session id by
+itself grants no access and revoking a key stops its sessions being served
+within a minute. The API key is never read from a query parameter.
+
+Because authentication happens before routing, this applies to the documentation
+tools too: unlike stdio mode, they are not reachable without a valid key.
+
+Three routes do not take the bearer. `/health` reports liveness only.
+`/.well-known/oauth-authorization-server` is the discovery document clients read
+before they hold a token. `/oauth/token` exchanges an API key, sent as
+`client_secret` in the form body, for a short-lived access token; it verifies
+that key against the LangWatch API before issuing anything, and the token it
+returns is what later MCP requests carry.
+
+The server listens on `127.0.0.1` by default, per the MCP transport guidance for
+local servers. Pass `--host 0.0.0.0` to accept connections from other machines,
+and only behind a network boundary you trust.
+
+Requests carrying a browser `Origin` header are checked against an allowlist.
+Loopback origins are always allowed; anything else has to be listed:
+
+```bash
+npx @langwatch/mcp-server --http --port 3000 \
+  --allowedOrigin https://your-app.example.com
+```
+
+#### Running behind a proxy
+
+Forwarded proxy headers resolve the external scheme that the OAuth metadata
+document advertises, so they are read by default.
+
+They do not decide the rate limit. Failed authentication is limited per client
+address, and that address comes from the socket rather than from
+`X-Forwarded-For`, so a client reaching the port directly cannot rotate a header
+to reset its own counter. Behind a real proxy every request shares the proxy's
+socket address, which means the whole proxy is limited as one client. Set
+`LANGWATCH_MCP_TRUST_PROXY=true` there to limit per real client instead, and
+only when the proxy overwrites `X-Forwarded-For` on the way in.
+
+This is defense in depth, not the security boundary. API keys are verified
+against the LangWatch API before a session is created and re-checked on every
+request; the rate limit exists to make guessing expensive, not to decide who
+gets in. A spoofable rate limit does not let anyone authenticate.
 
 ## Tools
 

package/dist/{archive-project-KAZFHR4A.js → archive-project-4EQGLBJJ.js}

@@ -1,8 +1,9 @@
 import {
   archiveProject
-} from "./chunk-B6UV3JVI.js";
-import "./chunk-CAY57CKF.js";
-import "./chunk-KOO5733S.js";
+} from "./chunk-7RHG56OH.js";
+import "./chunk-A2LEVYQ5.js";
+import "./chunk-WT4PO4A3.js";
+import "./chunk-SAS5OB7F.js";
 
 // src/tools/archive-project.ts
 async function handleArchiveProject(params) {
@@ -16,4 +17,4 @@ async function handleArchiveProject(params) {
 export {
   handleArchiveProject
 };
-//# sourceMappingURL=archive-project-KAZFHR4A.js.map
+//# sourceMappingURL=archive-project-4EQGLBJJ.js.map

package/dist/{archive-scenario-6M2IB7Y2.js → archive-scenario-W6BXYDZ3.js}

@@ -1,8 +1,9 @@
 import {
   archiveScenario
-} from "./chunk-LTEJDL4V.js";
-import "./chunk-CAY57CKF.js";
-import "./chunk-KOO5733S.js";
+} from "./chunk-J42FWRJ2.js";
+import "./chunk-A2LEVYQ5.js";
+import "./chunk-WT4PO4A3.js";
+import "./chunk-SAS5OB7F.js";
 
 // src/tools/archive-scenario.ts
 async function handleArchiveScenario(params) {
@@ -16,4 +17,4 @@ async function handleArchiveScenario(params) {
 export {
   handleArchiveScenario
 };
-//# sourceMappingURL=archive-scenario-6M2IB7Y2.js.map
+//# sourceMappingURL=archive-scenario-W6BXYDZ3.js.map

package/dist/{archive-suite-NXZ3YDS3.js → archive-suite-4T6BSRS7.js}

@@ -1,8 +1,9 @@
 import {
   archiveSuite
-} from "./chunk-UKRCZJJC.js";
-import "./chunk-CAY57CKF.js";
-import "./chunk-KOO5733S.js";
+} from "./chunk-YZLYHLLI.js";
+import "./chunk-A2LEVYQ5.js";
+import "./chunk-WT4PO4A3.js";
+import "./chunk-SAS5OB7F.js";
 
 // src/tools/archive-suite.ts
 async function handleArchiveSuite(params) {
@@ -12,4 +13,4 @@ async function handleArchiveSuite(params) {
 export {
   handleArchiveSuite
 };
-//# sourceMappingURL=archive-suite-NXZ3YDS3.js.map
+//# sourceMappingURL=archive-suite-4T6BSRS7.js.map

package/dist/{assign-prompt-tag-WPUJO55U.js → assign-prompt-tag-VLXUWEKU.js}

@@ -1,7 +1,8 @@
 import {
   assignPromptTag
-} from "./chunk-CAY57CKF.js";
-import "./chunk-KOO5733S.js";
+} from "./chunk-A2LEVYQ5.js";
+import "./chunk-WT4PO4A3.js";
+import "./chunk-SAS5OB7F.js";
 
 // src/tools/assign-prompt-tag.ts
 async function handleAssignPromptTag(params) {
@@ -16,4 +17,4 @@ async function handleAssignPromptTag(params) {
 export {
   handleAssignPromptTag
 };
-//# sourceMappingURL=assign-prompt-tag-WPUJO55U.js.map
+//# sourceMappingURL=assign-prompt-tag-VLXUWEKU.js.map

package/dist/chunk-37SMPMQS.js

@@ -0,0 +1,12 @@
+// src/utils/format-evaluations.ts
+function formatEvaluationLines(evaluations) {
+  return evaluations.map((evaluation) => {
+    const status = evaluation.passed === true ? "PASSED" : evaluation.passed === false ? "FAILED" : "N/A";
+    return `- **${evaluation.name || evaluation.evaluator_id}**: ${status}${evaluation.score != null ? ` (score: ${evaluation.score})` : ""}${evaluation.label ? ` [${evaluation.label}]` : ""}`;
+  });
+}
+
+export {
+  formatEvaluationLines
+};
+//# sourceMappingURL=chunk-37SMPMQS.js.map