@debugg-ai/debugg-ai-mcp 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to the DebuggAI MCP project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0]
+
+### Added — Remote transport: Streamable HTTP + OAuth Resource Server (opt-in)
+
+The server can now run as a hosted, multi-user remote MCP over **stateless
+Streamable HTTP**, in addition to the default stdio transport (which is
+unchanged). Enable with `DEBUGGAI_MCP_TRANSPORT=http` (+ `PORT`, default 3000).
+
+As an OAuth **Resource Server** (MCP 2025-06-18):
+- Each `POST /mcp` request must carry `Authorization: Bearer <token>`; the token
+  is request-scoped (AsyncLocalStorage) and used as the backend credential —
+  `api.debugg.ai` is the validator, so no token-verification keys live here.
+- Missing/invalid token → `401` with `WWW-Authenticate: Bearer resource_metadata=…`.
+- Serves RFC 9728 metadata at `/.well-known/oauth-protected-resource` advertising
+  the authorization server (`auth.debugg.ai`), so clients run the OAuth flow and
+  retry with a token.
+- `GET /health` for load-balancer / ECS health checks.
+
+Auth became request-scoped without touching the ~20 backend-client call sites:
+`config.api.key` resolves the per-request token when set (`utils/requestContext.ts`).
+Config env: `DEBUGGAI_MCP_TRANSPORT`, `PORT`, `DEBUGGAI_MCP_PUBLIC_URL`,
+`DEBUGGAI_OAUTH_ISSUER`, `DEBUGGAI_TOKEN_TYPE=bearer`. stdio installs need none of these.
+
+## [3.4.0]
+
+### Added — MCP Resources (browse projects / environments / executions)
+
+The server now declares the `resources` capability and exposes the read-only
+entities as addressable resources, so clients can browse and @-mention them as
+context instead of only calling tools:
+
+- **Collections** (`resources/list`): `debugg-ai://projects`, `debugg-ai://environments`, `debugg-ai://executions`
+- **Templates** (`resources/templates/list`): `debugg-ai://project/{uuid}`, `debugg-ai://environment/{uuid}`, `debugg-ai://execution/{uuid}`
+- **`resources/read`** dispatches each URI to the same entity handler the tools
+  use — identical data + auth, no drift — and returns the JSON payload.
+
+Additive: clients without resource support keep using the tools unchanged.
+Implementation in `handlers/resourcesHandler.ts`.
+
 ## [3.3.0]
 
 ### Added — Run artifacts returned as resource links

package/README.md

@@ -158,6 +158,24 @@ Every filter-mode response is paginated. Response shape:
 
 Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped). No response is ever silently truncated.
 
+## Resources
+
+Alongside tools, the server exposes the read-only entities as MCP **resources**
+so clients can browse and @-mention them as context:
+
+| URI | What |
+|---|---|
+| `debugg-ai://projects` | All projects (first page) |
+| `debugg-ai://environments` | Environments for the auto-detected project |
+| `debugg-ai://executions` | Recent executions (first page) |
+| `debugg-ai://project/{uuid}` | One project, full detail |
+| `debugg-ai://environment/{uuid}` | One environment (credentials inline, passwords redacted) |
+| `debugg-ai://execution/{uuid}` | One execution, full node detail + artifact links |
+
+Reads dispatch to the same handlers as the `project` / `environment` /
+`executions` tools, so the data and auth are identical. Resources are additive —
+clients without resource support keep using the tools.
+
 ### Security invariants
 
 - Passwords are write-only. They never appear in any response body from any tool.
@@ -216,6 +234,37 @@ Response-shape changes: the bare `count` field on list responses is gone — use
 DEBUGGAI_API_KEY=your_api_key
 ```
 
+## Remote / HTTP transport (optional)
+
+By default the server speaks **stdio** (local `npx`). It can instead run as a
+hosted, multi-user remote MCP over **stateless Streamable HTTP** + OAuth:
+
+```bash
+DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest
+```
+
+It is an OAuth **Resource Server**: every `POST /mcp` needs
+`Authorization: Bearer <token>`; missing/invalid tokens get a `401` with a
+`WWW-Authenticate` pointing at the RFC 9728 metadata, and clients run the OAuth
+flow against the advertised authorization server. The bearer is request-scoped —
+`api.debugg.ai` validates it.
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /mcp` | MCP Streamable HTTP (bearer-protected) |
+| `GET /.well-known/oauth-protected-resource` | RFC 9728 metadata (authorization server discovery) |
+| `GET /health` | Load-balancer / ECS health check |
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `DEBUGGAI_MCP_TRANSPORT` | `stdio` | Set to `http` for the remote transport |
+| `PORT` | `3000` | HTTP listen port |
+| `DEBUGGAI_MCP_PUBLIC_URL` | `https://mcp.debugg.ai` | This server's public resource URL (RFC 9728 `resource`) |
+| `DEBUGGAI_OAUTH_ISSUER` | `https://auth.debugg.ai` | Authorization server advertised to clients |
+| `DEBUGGAI_TOKEN_TYPE` | `token` | Set to `bearer` so OAuth tokens forward as `Authorization: Bearer` |
+
+stdio installs need none of these.
+
 ## Telemetry
 
 The MCP server ships with telemetry enabled by default — an embedded write-only PostHog project key (`phc_*`) so the team can observe cache hit rates, poll cadence, tunnel reliability, and other operational metrics across the install base. Captured events:

package/dist/config/index.js

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { currentApiKey } from '../utils/requestContext.js';
 function findPackageVersion() {
     const __dir = dirname(fileURLToPath(import.meta.url));
     let dir = __dir;
@@ -113,7 +114,14 @@ let _config;
 export const config = {
     get server() { return getConfig().server; },
     get devMode() { return getConfig().devMode; },
-    get api() { return getConfig().api; },
+    // api.key is request-scoped under the HTTP transport: if a per-request token
+    // is set (AsyncLocalStorage), it overrides the env key for that request only.
+    // stdio / tests have no request store, so the env key is returned unchanged.
+    get api() {
+        const api = getConfig().api;
+        const requestKey = currentApiKey();
+        return requestKey ? { ...api, key: requestKey } : api;
+    },
     get defaults() { return getConfig().defaults; },
     get logging() { return getConfig().logging; },
     get telemetry() { return getConfig().telemetry; },

package/dist/handlers/resourcesHandler.js

@@ -0,0 +1,127 @@
+/**
+ * MCP Resources (epic pglam).
+ *
+ * Exposes the read-only entities (projects / environments / executions) as
+ * addressable resources so clients can browse and @-mention them as context
+ * instead of (or alongside) calling the `project`/`environment`/`executions`
+ * tools. Reads reuse the exact tool handlers — same data, same auth, no drift.
+ *
+ *   Collections (resources/list):     debugg-ai://projects | environments | executions
+ *   Items (resources/templates/list): debugg-ai://project/{uuid}
+ *                                     debugg-ai://environment/{uuid}
+ *                                     debugg-ai://execution/{uuid}
+ *
+ * Resources are additive: clients that don't support the capability simply
+ * keep using the tools.
+ */
+import { config } from '../config/index.js';
+import { MCPError, MCPErrorCode, } from '../types/index.js';
+import { projectHandler } from './projectHandler.js';
+import { environmentHandler } from './environmentHandler.js';
+import { executionsHandler } from './executionsHandler.js';
+const SCHEME = 'debugg-ai';
+const JSON_MIME = 'application/json';
+/** Concrete collection resources returned by resources/list. */
+export const RESOURCE_COLLECTIONS = [
+    {
+        uri: `${SCHEME}://projects`,
+        name: 'projects',
+        title: 'DebuggAI Projects',
+        description: 'All projects visible to this API key (first page).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uri: `${SCHEME}://environments`,
+        name: 'environments',
+        title: 'DebuggAI Environments',
+        description: 'Environments for the auto-detected project (credentials redacted).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uri: `${SCHEME}://executions`,
+        name: 'executions',
+        title: 'DebuggAI Executions',
+        description: 'Recent workflow executions (first page).',
+        mimeType: JSON_MIME,
+    },
+];
+/** URI templates returned by resources/templates/list. */
+export const RESOURCE_TEMPLATES = [
+    {
+        uriTemplate: `${SCHEME}://project/{uuid}`,
+        name: 'project',
+        title: 'DebuggAI Project',
+        description: 'A single project by UUID, with full detail.',
+        mimeType: JSON_MIME,
+    },
+    {
+        uriTemplate: `${SCHEME}://environment/{uuid}`,
+        name: 'environment',
+        title: 'DebuggAI Environment',
+        description: 'A single environment by UUID, with credentials inline (passwords redacted).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uriTemplate: `${SCHEME}://execution/{uuid}`,
+        name: 'execution',
+        title: 'DebuggAI Execution',
+        description: 'A single execution by UUID, with full node detail + artifact links.',
+        mimeType: JSON_MIME,
+    },
+];
+function readContext() {
+    return { timestamp: new Date() };
+}
+/** Pull the JSON payload that every entity handler emits as its single text block. */
+function payloadText(res) {
+    const text = res.content?.find((c) => c.type === 'text')?.text;
+    return typeof text === 'string' ? text : '{}';
+}
+// debugg-ai://<kind>            (collection)
+// debugg-ai://<kind>/<uuid>     (item)
+const URI_RE = new RegExp(`^${SCHEME}://([a-z]+)(?:/([^/?#]+))?$`);
+/**
+ * Resolve a debugg-ai:// resource URI by dispatching to the matching tool
+ * handler and wrapping its JSON payload as a resource content block.
+ */
+export async function readResource(uri) {
+    if (!config.api.key) {
+        throw new MCPError(MCPErrorCode.CONFIGURATION_ERROR, 'DEBUGGAI_API_KEY is not set. Configure it in your MCP server registration. Get a key at https://debugg.ai.', { missingEnvVars: ['DEBUGGAI_API_KEY'] });
+    }
+    const match = URI_RE.exec(uri);
+    if (!match) {
+        throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Unrecognized resource URI: ${uri}`);
+    }
+    const [, kind, id] = match;
+    const ctx = readContext();
+    const requireId = () => {
+        if (!id) {
+            throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Resource ${uri} requires a UUID: ${SCHEME}://${kind}/{uuid}`);
+        }
+        return id;
+    };
+    let res;
+    switch (kind) {
+        case 'projects':
+            res = await projectHandler({ action: 'list' }, ctx);
+            break;
+        case 'project':
+            res = await projectHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        case 'environments':
+            res = await environmentHandler({ action: 'list' }, ctx);
+            break;
+        case 'environment':
+            res = await environmentHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        case 'executions':
+            res = await executionsHandler({ action: 'list' }, ctx);
+            break;
+        case 'execution':
+            res = await executionsHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        default:
+            throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Unknown resource kind "${kind}" in ${uri}`);
+    }
+    return { contents: [{ uri, mimeType: JSON_MIME, text: payloadText(res) }] };
+}

package/dist/httpServer.js

@@ -0,0 +1,134 @@
+/**
+ * Streamable HTTP transport + OAuth Resource Server (epic lybfq).
+ *
+ * Opt-in remote transport: `DEBUGGAI_MCP_TRANSPORT=http` (stdio stays default).
+ * Stateless (no session id) so it scales behind a plain load balancer.
+ *
+ * Auth model — the MCP server is an OAuth **Resource Server**:
+ *   - Every /mcp request must carry `Authorization: Bearer <token>`.
+ *   - The token is stashed per-request (AsyncLocalStorage) and used as the
+ *     backend credential; api.debugg.ai is the real validator (a bad token 401s
+ *     on the first backend call). No token verification keys live here.
+ *   - Missing token → 401 + `WWW-Authenticate: Bearer resource_metadata=...`,
+ *     and we serve RFC 9728 metadata at /.well-known/oauth-protected-resource
+ *     pointing clients at auth.debugg.ai to run the OAuth flow.
+ *
+ * Deployment note: set DEBUGGAI_TOKEN_TYPE=bearer so the backend client forwards
+ * the OAuth token as `Authorization: Bearer` (not `Token`).
+ */
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { runWithApiKey } from './utils/requestContext.js';
+const PUBLIC_URL = (process.env.DEBUGGAI_MCP_PUBLIC_URL || 'https://mcp.debugg.ai').replace(/\/+$/, '');
+const OAUTH_ISSUER = (process.env.DEBUGGAI_OAUTH_ISSUER || 'https://auth.debugg.ai').replace(/\/+$/, '');
+const RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+const MCP_PATH = '/mcp';
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+/** RFC 9728 protected-resource metadata: tells clients which AS issues tokens. */
+export function protectedResourceMetadata() {
+    return {
+        resource: PUBLIC_URL,
+        authorization_servers: [OAUTH_ISSUER],
+        bearer_methods_supported: ['header'],
+    };
+}
+/** Extract the token from `Authorization: Bearer <t>` (or `Token <t>`). */
+export function bearerToken(authHeader) {
+    if (!authHeader)
+        return undefined;
+    const m = /^(?:Bearer|Token)\s+(.+)$/i.exec(authHeader.trim());
+    return m ? m[1].trim() : undefined;
+}
+function sendJson(res, code, body, extraHeaders = {}) {
+    const data = JSON.stringify(body);
+    res.writeHead(code, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        ...extraHeaders,
+    });
+    res.end(data);
+}
+function unauthorized(res) {
+    const metadataUrl = `${PUBLIC_URL}${RESOURCE_METADATA_PATH}`;
+    sendJson(res, 401, { error: 'unauthorized', error_description: 'Missing or invalid bearer token; authenticate via the linked authorization server.' }, { 'WWW-Authenticate': `Bearer resource_metadata="${metadataUrl}"` });
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        let aborted = false;
+        req.on('data', (chunk) => {
+            data += chunk;
+            if (data.length > MAX_BODY_BYTES && !aborted) {
+                aborted = true;
+                reject(new Error('request body too large'));
+            }
+        });
+        req.on('end', () => {
+            if (aborted)
+                return;
+            if (!data)
+                return resolve(undefined);
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+/** Start the stateless Streamable HTTP server. Resolves to the listening server. */
+export async function startHttpServer(opts) {
+    const { port, buildServer, logger } = opts;
+    const httpServer = createServer(async (req, res) => {
+        const path = new URL(req.url || '/', 'http://localhost').pathname;
+        // ECS / LB health check — no auth.
+        if (path === '/health' && req.method === 'GET') {
+            return sendJson(res, 200, { status: 'ok' });
+        }
+        // RFC 9728 protected-resource metadata — public discovery, no auth.
+        if (path === RESOURCE_METADATA_PATH && req.method === 'GET') {
+            return sendJson(res, 200, protectedResourceMetadata());
+        }
+        if (path === MCP_PATH) {
+            const token = bearerToken(req.headers['authorization']);
+            if (!token) {
+                logger.info('HTTP MCP request without bearer token → 401');
+                return unauthorized(res);
+            }
+            let body;
+            if (req.method === 'POST') {
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    return sendJson(res, 400, { error: 'invalid_request', error_description: 'Request body must be valid JSON' });
+                }
+            }
+            // Stateless: a fresh server + transport per request, scoped to this
+            // request's bearer token via AsyncLocalStorage (so config.api.key resolves
+            // to it for every backend call made while handling this request).
+            const srv = buildServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on('close', () => {
+                transport.close().catch(() => { });
+                srv.close().catch(() => { });
+            });
+            try {
+                await srv.connect(transport);
+                await runWithApiKey(token, () => transport.handleRequest(req, res, body));
+            }
+            catch (error) {
+                logger.error('HTTP MCP request failed', { error: error instanceof Error ? error.message : String(error) });
+                if (!res.headersSent)
+                    sendJson(res, 500, { error: 'internal_error' });
+            }
+            return;
+        }
+        sendJson(res, 404, { error: 'not_found' });
+    });
+    await new Promise((resolve) => httpServer.listen(port, resolve));
+    logger.info('HTTP transport listening', { port, resource: PUBLIC_URL, authorizationServer: OAUTH_ISSUER });
+    return httpServer;
+}

package/dist/index.js

@@ -18,9 +18,10 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "./config/index.js";
 import { initTools, getTools, getTool } from "./tools/index.js";
+import { readResource, RESOURCE_COLLECTIONS, RESOURCE_TEMPLATES } from "./handlers/resourcesHandler.js";
 import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError, Telemetry, TelemetryEvents, withStructuredContent, } from "./utils/index.js";
 import { MCPErrorCode, MCPError, } from "./types/index.js";
 // Logger and server are initialized lazily in main() to avoid triggering
@@ -39,18 +40,21 @@ function createMCPServer() {
             tools: {
                 listChanged: false,
             },
+            resources: {
+                listChanged: false,
+            },
         },
     });
 }
 /**
  * Create progress callback for tool execution
  */
-function createProgressCallback(progressToken) {
+function createProgressCallback(srv, progressToken) {
     if (!progressToken)
         return undefined;
     return async ({ progress, total, message }) => {
         try {
-            await server.notification({
+            await srv.notification({
                 method: "notifications/progress",
                 params: {
                     progressToken,
@@ -72,10 +76,21 @@ function createProgressCallback(progressToken) {
     };
 }
 /**
- * Register MCP request handlers. Called in main() after server is created.
+ * Build a fully-configured MCP Server (capabilities + all request handlers).
+ * The HTTP transport calls this once per request for stateless isolation; main()
+ * uses it for the long-lived stdio server.
+ */
+export function buildConfiguredServer() {
+    const srv = createMCPServer();
+    registerHandlers(srv);
+    return srv;
+}
+/**
+ * Register MCP request handlers on a server instance. Called for the stdio
+ * singleton in main(), and once per request by the HTTP transport (stateless).
  */
-function registerHandlers() {
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+function registerHandlers(srv) {
+    srv.setRequestHandler(CallToolRequestSchema, async (req) => {
         const typedReq = req;
         const requestId = `req_${Date.now()}`;
         const requestLogger = logger.child({ requestId });
@@ -109,7 +124,7 @@ function registerHandlers() {
                 requestId,
                 timestamp: new Date(),
             };
-            const progressCallback = createProgressCallback(typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
+            const progressCallback = createProgressCallback(srv, typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
             requestLogger.info(`Executing tool: ${name}`);
             const toolStart = Date.now();
             const result = await tool.handler(validatedInput, context, progressCallback);
@@ -130,11 +145,33 @@ function registerHandlers() {
             return createErrorResponse(mcpError, typedReq.params.name);
         }
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    srv.setRequestHandler(ListToolsRequestSchema, async () => {
         const tools = getTools();
         logger.info('Tools list requested', { toolCount: tools.length });
         return { tools };
     });
+    // Resources (epic pglam): browse projects/environments/executions as
+    // addressable read URIs. Reads dispatch to the same entity handlers as the
+    // tools, so data + auth stay consistent.
+    srv.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logger.info('Resources list requested', { resourceCount: RESOURCE_COLLECTIONS.length });
+        return { resources: RESOURCE_COLLECTIONS };
+    });
+    srv.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        return { resourceTemplates: RESOURCE_TEMPLATES };
+    });
+    srv.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const uri = req.params?.uri;
+        logger.info('Resource read requested', { uri });
+        try {
+            return await readResource(uri);
+        }
+        catch (error) {
+            const mcpError = toMCPError(error, 'resource read');
+            logger.error('Resource read failed', { uri, errorCode: mcpError.code, message: mcpError.message });
+            throw mcpError;
+        }
+    });
 }
 /**
  * Main server initialization and startup
@@ -144,19 +181,18 @@ async function main() {
         // Initialize logger and server here (not at module load time) so config
         // validation errors are caught by this try-catch instead of crashing.
         logger = new Logger({ module: 'main' });
-        server = createMCPServer();
-        // Register request handlers (they reference the `server` variable)
-        registerHandlers();
+        const transportMode = (process.env.DEBUGGAI_MCP_TRANSPORT || 'stdio').toLowerCase();
         logger.info('Starting DebuggAI MCP Server', {
             nodeVersion: process.version,
             platform: process.platform,
             architecture: process.arch,
-            pid: process.pid
+            pid: process.pid,
+            transport: transportMode,
         });
-        // NOTE: DEBUGGAI_API_KEY validation is deferred to the first tool call so
-        // MCP clients see a proper initialize response + a structured tool error,
-        // rather than the subprocess dying with "Failed to reconnect" (bead cma).
-        if (!config.api.key) {
+        // stdio is single-user: the API key comes from the environment and is
+        // validated at first tool call (bead cma). HTTP is multi-user: each request
+        // carries its own bearer token, so a missing env key at boot is expected.
+        if (transportMode !== 'http' && !config.api.key) {
             logger.warn('DEBUGGAI_API_KEY is not set. Server will boot but every tool call will return a ConfigurationError until the env var is configured.');
         }
         // Initialize telemetry: PostHog by default (public project key embedded
@@ -180,12 +216,28 @@ async function main() {
         // No API calls at boot. Project context is resolved lazily on first tool
         // invocation (list_environments / list_credentials / check_app_in_browser).
         initTools(null);
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
-        logger.info('DebuggAI MCP Server is running and ready to accept requests', {
-            transport: 'stdio',
-            toolsAvailable: getTools().map(t => t.name),
-        });
+        if (transportMode === 'http') {
+            // Remote/hosted transport (epic lybfq): stateless Streamable HTTP + OAuth
+            // Resource Server. stdio stays the default and is unaffected.
+            const { startHttpServer } = await import('./httpServer.js');
+            const port = Number(process.env.PORT) || 3000;
+            await startHttpServer({ port, buildServer: buildConfiguredServer, logger });
+            logger.info('DebuggAI MCP Server is running and ready to accept requests', {
+                transport: 'http',
+                port,
+                toolsAvailable: getTools().map(t => t.name),
+            });
+        }
+        else {
+            server = createMCPServer();
+            registerHandlers(server);
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+            logger.info('DebuggAI MCP Server is running and ready to accept requests', {
+                transport: 'stdio',
+                toolsAvailable: getTools().map(t => t.name),
+            });
+        }
     }
     catch (error) {
         logger.error('Failed to start DebuggAI MCP Server', {

package/dist/utils/requestContext.js

@@ -0,0 +1,24 @@
+/**
+ * Request-scoped context (epic lybfq).
+ *
+ * stdio is single-user: one API key from the environment for the whole process.
+ * The HTTP transport is multi-user: each request carries its own bearer token.
+ * Rather than thread a token through every handler + backend-client call site,
+ * we stash it in AsyncLocalStorage for the duration of the request and let
+ * `config.api.key` resolve it (see config/index.ts). Outside an HTTP request
+ * (i.e. stdio, or tests) the store is empty and the env key is used — so the
+ * stdio path is completely unchanged.
+ *
+ * This module intentionally has NO imports so any layer (incl. config) can use
+ * it without creating an import cycle.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** Run `fn` with a request-scoped API key (used by the HTTP transport per request). */
+export function runWithApiKey(apiKey, fn) {
+    return storage.run({ apiKey }, fn);
+}
+/** The request-scoped API key if inside runWithApiKey(), else undefined (stdio). */
+export function currentApiKey() {
+    return storage.getStore()?.apiKey;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {