@testdriverai/agent 7.11.146-canary → 7.11.147-test

package/docs/claude-mcp-plugin.mdx

@@ -65,6 +65,43 @@ This is the same config the plugin wires up for you — the plugin just bundles
 
 ---
 
+## Remote (hosted URL) install — no CLI, browser login
+
+TestDriver also runs a **hosted MCP server** you can connect to with just a URL. There is no `npx` command and no API key to paste: the server speaks OAuth 2.1, so your client opens a browser, you sign in with TestDriver, and the tools appear. It exposes the **full live tool set** (`session_start`, `find`, `click`, `type`, `assert`, …) plus the read-only data tools, all scoped to your team.
+
+Hosted endpoint:
+
+```text
+https://mcp.testdriver.ai/mcp
+```
+
+The server advertises its authorization server (Auth0) via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata at:
+
+```text
+https://mcp.testdriver.ai/.well-known/oauth-protected-resource
+```
+
+Spec-compliant clients discover and complete the OAuth flow automatically:
+
+- **Claude** — add a custom connector pointing at the URL above; Claude runs the browser login for you.
+- **VS Code / Copilot** — add a remote MCP server entry with the URL; VS Code handles the OAuth handshake.
+- **ChatGPT** — add it as a connector by URL.
+- **Any spec-compliant client** — point it at the URL; it will read the metadata, sign you in, and connect.
+
+```json
+{
+  "mcpServers": {
+    "testdriver": {
+      "url": "https://mcp.testdriver.ai/mcp"
+    }
+  }
+}
+```
+
+Each connection gets its own isolated sandbox, so multiple people (or multiple chats) can run tests at the same time without interfering. The API-key paths above still work for automation and CI.
+
+---
+
 ## Observing test runs via HTTP MCP
 
 TestDriver also exposes **test results and analytics** over an HTTP MCP endpoint, so Claude Code (or any MCP-compatible client) can inspect your test runs, failures, and filters without provisioning a sandbox.

package/mcp-server/Dockerfile

@@ -0,0 +1,29 @@
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+COPY sdk/mcp-server/package*.json ./
+RUN npm ci --ignore-scripts
+
+COPY sdk/mcp-server/ ./
+RUN npm run build:server
+
+FROM node:22-alpine AS runtime
+
+WORKDIR /app
+
+COPY sdk/mcp-server/package*.json ./
+RUN npm ci --ignore-scripts --omit-dev
+
+COPY --from=builder /app/dist ./dist
+
+ENV NODE_ENV=production
+ENV PORT=8080
+# Hosted Streamable HTTP transport with Auth0 OAuth enforcement, bound for Fly.
+ENV TD_MCP_TRANSPORT=http
+ENV TD_MCP_AUTH=oauth
+ENV TD_MCP_HOST=0.0.0.0
+
+EXPOSE 8080
+
+CMD ["node", "dist/server.mjs"]

package/mcp-server/dist/http-auth.d.ts

@@ -0,0 +1,38 @@
+/**
+ * http-auth.ts
+ *
+ * OAuth 2.0 Resource Server helpers for the standalone TestDriver MCP server's
+ * Streamable HTTP transport. Identity is delegated to Auth0 — this server only
+ * *validates* the Bearer JWTs Auth0 issues for the TestDriver API audience and
+ * advertises Auth0 as the authorization server via RFC 9728 metadata.
+ *
+ * When OAuth is disabled (no `TD_MCP_AUTH=oauth`), everything here is a no-op so
+ * local stdio / trusted-network usage is unchanged.
+ */
+import type { IncomingMessage } from "http";
+import { type JWTPayload } from "jose";
+/** Whether OAuth enforcement is enabled for the HTTP transport. */
+export declare function isOAuthEnabled(): boolean;
+/** RFC 9728 protected resource metadata document. */
+export declare function protectedResourceMetadata(req: IncomingMessage, mcpPath: string): Record<string, unknown>;
+/** Build the `WWW-Authenticate` challenge header value. */
+export declare function wwwAuthenticate(req: IncomingMessage, opts?: {
+    error?: string;
+    description?: string;
+}): string;
+/** Result of an authentication attempt. */
+export type AuthResult = {
+    ok: true;
+    claims: JWTPayload;
+    token: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    description: string;
+};
+/**
+ * Authenticate an incoming request against Auth0. Returns the verified claims
+ * on success, or an error descriptor the caller turns into a 401 challenge.
+ */
+export declare function authenticate(req: IncomingMessage): Promise<AuthResult>;

package/mcp-server/dist/http-auth.js

@@ -0,0 +1,135 @@
+/**
+ * http-auth.ts
+ *
+ * OAuth 2.0 Resource Server helpers for the standalone TestDriver MCP server's
+ * Streamable HTTP transport. Identity is delegated to Auth0 — this server only
+ * *validates* the Bearer JWTs Auth0 issues for the TestDriver API audience and
+ * advertises Auth0 as the authorization server via RFC 9728 metadata.
+ *
+ * When OAuth is disabled (no `TD_MCP_AUTH=oauth`), everything here is a no-op so
+ * local stdio / trusted-network usage is unchanged.
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+/** Whether OAuth enforcement is enabled for the HTTP transport. */
+export function isOAuthEnabled() {
+    return (process.env.TD_MCP_AUTH || "").toLowerCase() === "oauth";
+}
+/** Canonical resource identifier (RFC 8707) = the Auth0 API audience. */
+const MCP_AUDIENCE = process.env.TD_AUTH0_AUDIENCE || "https://api.testdriver.ai";
+/** Auth0 issuer(s) trusted to mint tokens. Comma-separated env override. */
+const TRUSTED_ISSUERS = (process.env.TD_MCP_TRUSTED_ISSUERS ||
+    (process.env.AUTH0_DOMAIN
+        ? `https://${String(process.env.AUTH0_DOMAIN)
+            .replace(/^https?:\/\//, "")
+            .replace(/\/$/, "")}/`
+        : "https://replayable.us.auth0.com/"))
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+// One remote JWKS per issuer; jose caches keys and handles rotation.
+const jwksByIssuer = new Map();
+function jwksForIssuer(issuer) {
+    let jwks = jwksByIssuer.get(issuer);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(`${issuer.replace(/\/$/, "")}/.well-known/jwks.json`));
+        jwksByIssuer.set(issuer, jwks);
+    }
+    return jwks;
+}
+/** Scheme the client used to reach us (honours a TLS-terminating proxy). */
+function requestScheme(req) {
+    const forwarded = req.headers["x-forwarded-proto"];
+    if (forwarded) {
+        return Array.isArray(forwarded) ? forwarded[0] : forwarded.split(",")[0];
+    }
+    const socket = req.socket;
+    return socket && socket.encrypted ? "https" : "http";
+}
+/** The public URL clients use to reach this server's MCP endpoint. */
+function resourceUrl(req, mcpPath) {
+    if (process.env.TD_MCP_RESOURCE) {
+        return process.env.TD_MCP_RESOURCE;
+    }
+    const host = req.headers["x-forwarded-host"] || req.headers.host;
+    return `${requestScheme(req)}://${host}${mcpPath}`;
+}
+/** RFC 9728 protected resource metadata document. */
+export function protectedResourceMetadata(req, mcpPath) {
+    return {
+        resource: resourceUrl(req, mcpPath),
+        authorization_servers: TRUSTED_ISSUERS.map((iss) => iss.replace(/\/$/, "")),
+        bearer_methods_supported: ["header"],
+        scopes_supported: ["openid", "profile", "email"],
+        resource_documentation: "https://docs.testdriver.ai",
+    };
+}
+/** Build the `WWW-Authenticate` challenge header value. */
+export function wwwAuthenticate(req, opts) {
+    const host = req.headers["x-forwarded-host"] || req.headers.host;
+    const metadataUrl = `${requestScheme(req)}://${host}/.well-known/oauth-protected-resource`;
+    let challenge = `Bearer resource_metadata="${metadataUrl}"`;
+    if (opts?.error) {
+        challenge += `, error="${opts.error}"`;
+    }
+    if (opts?.description) {
+        challenge += `, error_description="${opts.description}"`;
+    }
+    return challenge;
+}
+/** Extract a Bearer token from the Authorization header, or null. */
+function bearerFromRequest(req) {
+    const auth = req.headers.authorization;
+    if (!auth) {
+        return null;
+    }
+    const m = /^Bearer\s+(.+)$/i.exec(auth);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Authenticate an incoming request against Auth0. Returns the verified claims
+ * on success, or an error descriptor the caller turns into a 401 challenge.
+ */
+export async function authenticate(req) {
+    const token = bearerFromRequest(req);
+    if (!token) {
+        return {
+            ok: false,
+            status: 401,
+            error: "invalid_request",
+            description: "Authentication required",
+        };
+    }
+    // Read the unverified issuer to select the right JWKS, then verify.
+    let issuer;
+    try {
+        const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf-8"));
+        issuer = payload.iss;
+    }
+    catch {
+        issuer = undefined;
+    }
+    if (!issuer || !TRUSTED_ISSUERS.includes(issuer)) {
+        return {
+            ok: false,
+            status: 401,
+            error: "invalid_token",
+            description: "Untrusted or missing token issuer",
+        };
+    }
+    try {
+        const { payload } = await jwtVerify(token, jwksForIssuer(issuer), {
+            issuer,
+            audience: MCP_AUDIENCE,
+            algorithms: ["RS256"],
+        });
+        return { ok: true, claims: payload, token };
+    }
+    catch {
+        return {
+            ok: false,
+            status: 401,
+            error: "invalid_token",
+            description: "Invalid or expired access token",
+        };
+    }
+}

package/mcp-server/dist/server.mjs

@@ -23,6 +23,7 @@ import { z } from "zod";
 import * as core from "./core/actions.js";
 import { NoActiveSessionError } from "./core/actions.js";
 import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
+import { authenticate, isOAuthEnabled, protectedResourceMetadata, wwwAuthenticate } from "./http-auth.js";
 import { SessionStartInputSchema } from "./provision-types.js";
 // =============================================================================
 // Sentry
@@ -192,6 +193,12 @@ function imageStoreState() {
     }
     return state;
 }
+/** Per-session team API key resolved from the caller's OAuth token (hosted mode).
+ *  Null when unset, so session_start falls back to the process-wide env key. */
+function sessionApiKey() {
+    const key = core.getAdapterState().apiKey;
+    return typeof key === "string" && key.length > 0 ? key : undefined;
+}
 /**
  * Store an image and return its unique resource URI
  */
@@ -565,7 +572,7 @@ Debug mode (connect to existing sandbox):
                 : "Starting session...");
             let result;
             try {
-                result = await raceAbort(extra.signal, "session_start", core.sessionStart(params, { os: resolvedOs, e2bTemplateId: resolvedE2bTemplateId }, { onProgress: (m) => progress.report(m) }));
+                result = await raceAbort(extra.signal, "session_start", core.sessionStart(params, { os: resolvedOs, e2bTemplateId: resolvedE2bTemplateId, apiKey: sessionApiKey() }, { onProgress: (m) => progress.report(m) }));
             }
             finally {
                 stopHeartbeat();
@@ -1564,8 +1571,79 @@ Learn more at https://docs.testdriver.ai/v7/getting-started/
             throw error;
         }
     });
+    // =============================================================================
+    // Data tools — read TestDriver run history via the backend REST API, scoped to
+    // the caller's team by their OAuth token (hosted mode) or env API key.
+    // =============================================================================
+    server.registerTool("list_test_runs", {
+        description: "List recent TestDriver test runs for the current team.",
+        inputSchema: z.object({
+            page: z.number().optional().describe("Page number (1-indexed)"),
+            limit: z.number().optional().describe("Maximum number of test runs to return"),
+            status: z.string().optional().describe("Filter by test run status"),
+            platform: z.string().optional().describe("Filter by platform"),
+            branch: z.string().optional().describe("Filter by git branch"),
+            testFile: z.string().optional().describe("Filter by test file path"),
+            search: z.string().optional().describe("Search by suite name substring"),
+        }),
+    }, async (params) => {
+        try {
+            const data = await backendGet("/api/v1/testdriver/test-runs-list", params);
+            return createToolResult(true, JSON.stringify(data, null, 2), { action: "list_test_runs" });
+        }
+        catch (error) {
+            logger.error("list_test_runs: Failed", { error: String(error) });
+            captureException(error, { tags: { tool: "list_test_runs" } });
+            return createToolResult(false, `Failed to list test runs: ${String(error)}`, { action: "list_test_runs" });
+        }
+    });
+    server.registerTool("get_test_run_detail", {
+        description: "Get details for a single TestDriver test run, including its test cases.",
+        inputSchema: z.object({
+            id: z.string().describe("The test run id"),
+        }),
+    }, async (params) => {
+        try {
+            const data = await backendGet("/api/v1/testdriver/test-run-detail", { id: params.id });
+            return createToolResult(true, JSON.stringify(data, null, 2), { action: "get_test_run_detail" });
+        }
+        catch (error) {
+            logger.error("get_test_run_detail: Failed", { error: String(error) });
+            captureException(error, { tags: { tool: "get_test_run_detail" } });
+            return createToolResult(false, `Failed to get test run detail: ${String(error)}`, { action: "get_test_run_detail" });
+        }
+    });
     return server;
 }
+/**
+ * Call a backend REST endpoint as the current session's team. Prefers the
+ * caller's OAuth Bearer (hosted mode); otherwise sends the env API key via
+ * `X-Api-Key` (stdio / local mode).
+ */
+async function backendGet(pathname, query) {
+    const apiRoot = (process.env.TD_API_ROOT || "https://api.testdriver.ai").replace(/\/$/, "");
+    const url = new URL(`${apiRoot}${pathname}`);
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== "") {
+            url.searchParams.set(k, String(v));
+        }
+    }
+    const adapter = core.getAdapterState();
+    const headers = { accept: "application/json" };
+    const token = adapter.oauthToken;
+    const apiKey = adapter.apiKey || process.env.TD_API_KEY || process.env.COPILOT_MCP_TD_API_KEY;
+    if (typeof token === "string" && token) {
+        headers.authorization = `Bearer ${token}`;
+    }
+    else if (typeof apiKey === "string" && apiKey) {
+        headers["x-api-key"] = apiKey;
+    }
+    const resp = await fetch(url.toString(), { headers });
+    if (!resp.ok) {
+        throw new Error(`backend ${pathname} returned ${resp.status}`);
+    }
+    return resp.json();
+}
 /** Read and JSON-parse a request body. Returns undefined for an empty/invalid
  *  body (GET/DELETE carry none) so callers can treat "no body" uniformly. */
 function readJsonBody(req) {
@@ -1606,6 +1684,46 @@ function readJsonBody(req) {
  * or otherwise protected outside the MCP layer). Do not expose this on a public
  * network without putting a real authenticating proxy in front of it.
  */
+/**
+ * Exchange a verified Auth0 access token for the caller's native TestDriver team
+ * API key via the backend, so each hosted session provisions under the right
+ * team and quota. Returns null if the exchange fails (caller falls back / errors).
+ */
+async function exchangeOAuthTokenForApiKey(token) {
+    const apiRoot = process.env.TD_API_ROOT || "https://api.testdriver.ai";
+    try {
+        const resp = await fetch(`${apiRoot.replace(/\/$/, "")}/auth/exchange-oauth-token`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({}),
+        });
+        if (!resp.ok) {
+            logger.warn("http: exchange-oauth-token failed", { status: resp.status });
+            return null;
+        }
+        const data = (await resp.json());
+        return data.apiKey || null;
+    }
+    catch (error) {
+        logger.error("http: exchange-oauth-token error", { error: String(error) });
+        return null;
+    }
+}
+// Fly.io machine that owns this process. When set (hosted, multi-machine), we
+// tag it into each session id so a request landing on the wrong machine can be
+// replayed to the owner via the `fly-replay` header — session affinity without a
+// shared store. Empty locally / single-machine, where every request is already
+// local.
+const FLY_MACHINE_ID = process.env.FLY_MACHINE_ID || "";
+// Session ids are `<uuid>.<machineId>` in multi-machine mode. These split the
+// two back out; a plain uuid (no dot) means single-machine and owns itself.
+function sessionOwnerMachine(sid) {
+    const dot = sid.lastIndexOf(".");
+    return dot === -1 ? "" : sid.slice(dot + 1);
+}
 async function startHttpServer() {
     const host = process.env.TD_MCP_HOST || "127.0.0.1";
     const port = Number(process.env.TD_MCP_PORT || process.env.PORT || 8788);
@@ -1621,11 +1739,44 @@ async function startHttpServer() {
                 res.end(JSON.stringify({ status: "ok", server: "testdriver", version, sessions: connections.size }));
                 return;
             }
+            // RFC 9728 protected-resource metadata so OAuth clients discover Auth0.
+            // Only advertised when OAuth is enforced. Some clients append the resource
+            // path to the well-known URL, so match both.
+            if (isOAuthEnabled() &&
+                req.method === "GET" &&
+                (url.pathname === "/.well-known/oauth-protected-resource" ||
+                    url.pathname === `/.well-known/oauth-protected-resource${mcpPath}`)) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify(protectedResourceMetadata(req, mcpPath)));
+                return;
+            }
             if (url.pathname !== mcpPath) {
                 res.writeHead(404, { "content-type": "application/json" });
                 res.end(JSON.stringify({ error: "Not found", hint: `MCP endpoint is ${mcpPath}` }));
                 return;
             }
+            // OAuth resource-server enforcement (only when TD_MCP_AUTH=oauth). When
+            // disabled this is a no-op so local/trusted-network usage is unchanged.
+            let resolvedApiKey = null;
+            let resolvedToken = null;
+            if (isOAuthEnabled()) {
+                const auth = await authenticate(req);
+                if (!auth.ok) {
+                    res.writeHead(auth.status, {
+                        "content-type": "application/json",
+                        "www-authenticate": wwwAuthenticate(req, { error: auth.error, description: auth.description }),
+                    });
+                    res.end(JSON.stringify({ error: auth.error, error_description: auth.description }));
+                    return;
+                }
+                resolvedToken = auth.token;
+                resolvedApiKey = await exchangeOAuthTokenForApiKey(auth.token);
+                if (!resolvedApiKey) {
+                    res.writeHead(403, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "no_team", error_description: "No TestDriver team is linked to this account" }));
+                    return;
+                }
+            }
             const sessionId = req.headers["mcp-session-id"];
             const sid = Array.isArray(sessionId) ? sessionId[0] : sessionId;
             // POST bodies must be parsed here (to detect `initialize` and to hand the
@@ -1635,6 +1786,15 @@ async function startHttpServer() {
             // A brand-new session: only an `initialize` request may create one.
             if (!connection) {
                 if (sid) {
+                    // The session lives on another Fly machine: ask Fly's proxy to replay
+                    // this request there instead of 404ing (which would force a new
+                    // sandbox). Only when the owner is a *different* known machine.
+                    const owner = sessionOwnerMachine(sid);
+                    if (FLY_MACHINE_ID && owner && owner !== FLY_MACHINE_ID) {
+                        res.writeHead(409, { "fly-replay": `instance=${owner}` });
+                        res.end();
+                        return;
+                    }
                     // Client presented a session id we don't know — it was torn down or is
                     // stale. 404 so the client re-initializes (matches SDK stateful mode).
                     res.writeHead(404, { "content-type": "application/json" });
@@ -1648,9 +1808,21 @@ async function startHttpServer() {
                 }
                 // Mint an isolated context + a server bound to it + a transport.
                 const ctx = core.createIsolatedContext();
+                // Seed the per-session team key so session_start provisions under the
+                // caller's own team (hosted OAuth mode). Falls back to env when unset.
+                if (resolvedApiKey) {
+                    ctx.adapter.apiKey = resolvedApiKey;
+                }
+                // Keep the caller's Bearer so data tools can call the backend REST API as
+                // the authenticated user.
+                if (resolvedToken) {
+                    ctx.adapter.oauthToken = resolvedToken;
+                }
                 const mcpServer = buildServer();
                 const transport = new StreamableHTTPServerTransport({
-                    sessionIdGenerator: () => randomUUID(),
+                    // Tag the owning machine into the id (multi-machine only) so later
+                    // requests can be replayed here via `fly-replay`.
+                    sessionIdGenerator: () => (FLY_MACHINE_ID ? `${randomUUID()}.${FLY_MACHINE_ID}` : randomUUID()),
                     onsessioninitialized: (newId) => {
                         connections.set(newId, { transport, server: mcpServer, ctx });
                         logger.info("http: MCP session initialized", { sessionId: newId, activeSessions: connections.size });

package/mcp-server/package-lock.json

@@ -11,7 +11,7 @@
         "@modelcontextprotocol/ext-apps": "^1.0.0",
         "@modelcontextprotocol/sdk": "^1.24.0",
         "@sentry/node": "^9.0.0",
-        "jose": "^6.2.12",
+        "jose": "^5.10.0",
         "semver": "^7.7.4",
         "zod": "^3.24.0"
       },
@@ -569,6 +569,15 @@
         }
       }
     },
+    "node_modules/@modelcontextprotocol/sdk/node_modules/jose": {
+      "version": "6.2.12",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.12.tgz",
+      "integrity": "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
     "node_modules/@opentelemetry/api": {
       "version": "1.9.0",
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz",
@@ -2763,9 +2772,9 @@
       "license": "ISC"
     },
     "node_modules/jose": {
-      "version": "6.2.12",
-      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.12.tgz",
-      "integrity": "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==",
+      "version": "5.10.0",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-5.10.0.tgz",
+      "integrity": "sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg==",
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/panva"

package/mcp-server/package.json

@@ -18,6 +18,7 @@
     "@modelcontextprotocol/ext-apps": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.24.0",
     "@sentry/node": "^9.0.0",
+    "jose": "^5.10.0",
     "semver": "^7.7.4",
     "zod": "^3.24.0"
   },

package/mcp-server/src/http-auth.ts

@@ -0,0 +1,169 @@
+/**
+ * http-auth.ts
+ *
+ * OAuth 2.0 Resource Server helpers for the standalone TestDriver MCP server's
+ * Streamable HTTP transport. Identity is delegated to Auth0 — this server only
+ * *validates* the Bearer JWTs Auth0 issues for the TestDriver API audience and
+ * advertises Auth0 as the authorization server via RFC 9728 metadata.
+ *
+ * When OAuth is disabled (no `TD_MCP_AUTH=oauth`), everything here is a no-op so
+ * local stdio / trusted-network usage is unchanged.
+ */
+
+import type { IncomingMessage } from "http";
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+
+/** Whether OAuth enforcement is enabled for the HTTP transport. */
+export function isOAuthEnabled(): boolean {
+  return (process.env.TD_MCP_AUTH || "").toLowerCase() === "oauth";
+}
+
+/** Canonical resource identifier (RFC 8707) = the Auth0 API audience. */
+const MCP_AUDIENCE =
+  process.env.TD_AUTH0_AUDIENCE || "https://api.testdriver.ai";
+
+/** Auth0 issuer(s) trusted to mint tokens. Comma-separated env override. */
+const TRUSTED_ISSUERS = (
+  process.env.TD_MCP_TRUSTED_ISSUERS ||
+  (process.env.AUTH0_DOMAIN
+    ? `https://${String(process.env.AUTH0_DOMAIN)
+        .replace(/^https?:\/\//, "")
+        .replace(/\/$/, "")}/`
+    : "https://replayable.us.auth0.com/")
+)
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+// One remote JWKS per issuer; jose caches keys and handles rotation.
+const jwksByIssuer = new Map<
+  string,
+  ReturnType<typeof createRemoteJWKSet>
+>();
+
+function jwksForIssuer(issuer: string): ReturnType<typeof createRemoteJWKSet> {
+  let jwks = jwksByIssuer.get(issuer);
+  if (!jwks) {
+    jwks = createRemoteJWKSet(
+      new URL(`${issuer.replace(/\/$/, "")}/.well-known/jwks.json`),
+    );
+    jwksByIssuer.set(issuer, jwks);
+  }
+  return jwks;
+}
+
+/** Scheme the client used to reach us (honours a TLS-terminating proxy). */
+function requestScheme(req: IncomingMessage): string {
+  const forwarded = req.headers["x-forwarded-proto"];
+  if (forwarded) {
+    return Array.isArray(forwarded) ? forwarded[0] : forwarded.split(",")[0];
+  }
+  const socket = req.socket as { encrypted?: boolean } | undefined;
+  return socket && socket.encrypted ? "https" : "http";
+}
+
+/** The public URL clients use to reach this server's MCP endpoint. */
+function resourceUrl(req: IncomingMessage, mcpPath: string): string {
+  if (process.env.TD_MCP_RESOURCE) {
+    return process.env.TD_MCP_RESOURCE;
+  }
+  const host = req.headers["x-forwarded-host"] || req.headers.host;
+  return `${requestScheme(req)}://${host}${mcpPath}`;
+}
+
+/** RFC 9728 protected resource metadata document. */
+export function protectedResourceMetadata(
+  req: IncomingMessage,
+  mcpPath: string,
+): Record<string, unknown> {
+  return {
+    resource: resourceUrl(req, mcpPath),
+    authorization_servers: TRUSTED_ISSUERS.map((iss) => iss.replace(/\/$/, "")),
+    bearer_methods_supported: ["header"],
+    scopes_supported: ["openid", "profile", "email"],
+    resource_documentation: "https://docs.testdriver.ai",
+  };
+}
+
+/** Build the `WWW-Authenticate` challenge header value. */
+export function wwwAuthenticate(
+  req: IncomingMessage,
+  opts?: { error?: string; description?: string },
+): string {
+  const host = req.headers["x-forwarded-host"] || req.headers.host;
+  const metadataUrl = `${requestScheme(req)}://${host}/.well-known/oauth-protected-resource`;
+  let challenge = `Bearer resource_metadata="${metadataUrl}"`;
+  if (opts?.error) {
+    challenge += `, error="${opts.error}"`;
+  }
+  if (opts?.description) {
+    challenge += `, error_description="${opts.description}"`;
+  }
+  return challenge;
+}
+
+/** Extract a Bearer token from the Authorization header, or null. */
+function bearerFromRequest(req: IncomingMessage): string | null {
+  const auth = req.headers.authorization;
+  if (!auth) {
+    return null;
+  }
+  const m = /^Bearer\s+(.+)$/i.exec(auth);
+  return m ? m[1].trim() : null;
+}
+
+/** Result of an authentication attempt. */
+export type AuthResult =
+  | { ok: true; claims: JWTPayload; token: string }
+  | { ok: false; status: number; error: string; description: string };
+
+/**
+ * Authenticate an incoming request against Auth0. Returns the verified claims
+ * on success, or an error descriptor the caller turns into a 401 challenge.
+ */
+export async function authenticate(req: IncomingMessage): Promise<AuthResult> {
+  const token = bearerFromRequest(req);
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      error: "invalid_request",
+      description: "Authentication required",
+    };
+  }
+
+  // Read the unverified issuer to select the right JWKS, then verify.
+  let issuer: string | undefined;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString("utf-8"),
+    );
+    issuer = payload.iss;
+  } catch {
+    issuer = undefined;
+  }
+  if (!issuer || !TRUSTED_ISSUERS.includes(issuer)) {
+    return {
+      ok: false,
+      status: 401,
+      error: "invalid_token",
+      description: "Untrusted or missing token issuer",
+    };
+  }
+
+  try {
+    const { payload } = await jwtVerify(token, jwksForIssuer(issuer), {
+      issuer,
+      audience: MCP_AUDIENCE,
+      algorithms: ["RS256"],
+    });
+    return { ok: true, claims: payload, token };
+  } catch {
+    return {
+      ok: false,
+      status: 401,
+      error: "invalid_token",
+      description: "Invalid or expired access token",
+    };
+  }
+}

package/mcp-server/src/server.ts

@@ -29,6 +29,7 @@ import { z } from "zod";
 import * as core from "./core/actions.js";
 import { NoActiveSessionError, type ActionResult } from "./core/actions.js";
 import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
+import { authenticate, isOAuthEnabled, protectedResourceMetadata, wwwAuthenticate } from "./http-auth.js";
 import { SessionStartInputSchema, type SessionStartInput } from "./provision-types.js";
 import { type SessionState } from "./session.js";
 
@@ -253,6 +254,13 @@ function imageStoreState(): ImageStoreState {
   return state;
 }
 
+/** Per-session team API key resolved from the caller's OAuth token (hosted mode).
+ *  Null when unset, so session_start falls back to the process-wide env key. */
+function sessionApiKey(): string | undefined {
+  const key = core.getAdapterState().apiKey;
+  return typeof key === "string" && key.length > 0 ? key : undefined;
+}
+
 /**
  * Store an image and return its unique resource URI
  */
@@ -736,7 +744,7 @@ Debug mode (connect to existing sandbox):
           "session_start",
           core.sessionStart(
             params,
-            { os: resolvedOs, e2bTemplateId: resolvedE2bTemplateId },
+            { os: resolvedOs, e2bTemplateId: resolvedE2bTemplateId, apiKey: sessionApiKey() },
             { onProgress: (m) => progress.report(m) }
           )
         );
@@ -1911,9 +1919,91 @@ Learn more at https://docs.testdriver.ai/v7/getting-started/
   }
 );
 
+// =============================================================================
+// Data tools — read TestDriver run history via the backend REST API, scoped to
+// the caller's team by their OAuth token (hosted mode) or env API key.
+// =============================================================================
+
+server.registerTool(
+  "list_test_runs",
+  {
+    description: "List recent TestDriver test runs for the current team.",
+    inputSchema: z.object({
+      page: z.number().optional().describe("Page number (1-indexed)"),
+      limit: z.number().optional().describe("Maximum number of test runs to return"),
+      status: z.string().optional().describe("Filter by test run status"),
+      platform: z.string().optional().describe("Filter by platform"),
+      branch: z.string().optional().describe("Filter by git branch"),
+      testFile: z.string().optional().describe("Filter by test file path"),
+      search: z.string().optional().describe("Search by suite name substring"),
+    }),
+  },
+  async (params): Promise<CallToolResult> => {
+    try {
+      const data = await backendGet("/api/v1/testdriver/test-runs-list", params as Record<string, unknown>);
+      return createToolResult(true, JSON.stringify(data, null, 2), { action: "list_test_runs" });
+    } catch (error) {
+      logger.error("list_test_runs: Failed", { error: String(error) });
+      captureException(error as Error, { tags: { tool: "list_test_runs" } });
+      return createToolResult(false, `Failed to list test runs: ${String(error)}`, { action: "list_test_runs" });
+    }
+  }
+);
+
+server.registerTool(
+  "get_test_run_detail",
+  {
+    description: "Get details for a single TestDriver test run, including its test cases.",
+    inputSchema: z.object({
+      id: z.string().describe("The test run id"),
+    }),
+  },
+  async (params): Promise<CallToolResult> => {
+    try {
+      const data = await backendGet("/api/v1/testdriver/test-run-detail", { id: params.id });
+      return createToolResult(true, JSON.stringify(data, null, 2), { action: "get_test_run_detail" });
+    } catch (error) {
+      logger.error("get_test_run_detail: Failed", { error: String(error) });
+      captureException(error as Error, { tags: { tool: "get_test_run_detail" } });
+      return createToolResult(false, `Failed to get test run detail: ${String(error)}`, { action: "get_test_run_detail" });
+    }
+  }
+);
+
   return server;
 }
 
+/**
+ * Call a backend REST endpoint as the current session's team. Prefers the
+ * caller's OAuth Bearer (hosted mode); otherwise sends the env API key via
+ * `X-Api-Key` (stdio / local mode).
+ */
+async function backendGet(pathname: string, query: Record<string, unknown>): Promise<unknown> {
+  const apiRoot = (process.env.TD_API_ROOT || "https://api.testdriver.ai").replace(/\/$/, "");
+  const url = new URL(`${apiRoot}${pathname}`);
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== undefined && v !== null && v !== "") {
+      url.searchParams.set(k, String(v));
+    }
+  }
+
+  const adapter = core.getAdapterState();
+  const headers: Record<string, string> = { accept: "application/json" };
+  const token = adapter.oauthToken;
+  const apiKey = adapter.apiKey || process.env.TD_API_KEY || process.env.COPILOT_MCP_TD_API_KEY;
+  if (typeof token === "string" && token) {
+    headers.authorization = `Bearer ${token}`;
+  } else if (typeof apiKey === "string" && apiKey) {
+    headers["x-api-key"] = apiKey;
+  }
+
+  const resp = await fetch(url.toString(), { headers });
+  if (!resp.ok) {
+    throw new Error(`backend ${pathname} returned ${resp.status}`);
+  }
+  return resp.json();
+}
+
 
 // =============================================================================
 // HTTP transport (Streamable HTTP, no auth)
@@ -1966,6 +2056,48 @@ function readJsonBody(req: http.IncomingMessage): Promise<unknown> {
  * or otherwise protected outside the MCP layer). Do not expose this on a public
  * network without putting a real authenticating proxy in front of it.
  */
+/**
+ * Exchange a verified Auth0 access token for the caller's native TestDriver team
+ * API key via the backend, so each hosted session provisions under the right
+ * team and quota. Returns null if the exchange fails (caller falls back / errors).
+ */
+async function exchangeOAuthTokenForApiKey(token: string): Promise<string | null> {
+  const apiRoot = process.env.TD_API_ROOT || "https://api.testdriver.ai";
+  try {
+    const resp = await fetch(`${apiRoot.replace(/\/$/, "")}/auth/exchange-oauth-token`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({}),
+    });
+    if (!resp.ok) {
+      logger.warn("http: exchange-oauth-token failed", { status: resp.status });
+      return null;
+    }
+    const data = (await resp.json()) as { apiKey?: string };
+    return data.apiKey || null;
+  } catch (error) {
+    logger.error("http: exchange-oauth-token error", { error: String(error) });
+    return null;
+  }
+}
+
+// Fly.io machine that owns this process. When set (hosted, multi-machine), we
+// tag it into each session id so a request landing on the wrong machine can be
+// replayed to the owner via the `fly-replay` header — session affinity without a
+// shared store. Empty locally / single-machine, where every request is already
+// local.
+const FLY_MACHINE_ID = process.env.FLY_MACHINE_ID || "";
+
+// Session ids are `<uuid>.<machineId>` in multi-machine mode. These split the
+// two back out; a plain uuid (no dot) means single-machine and owns itself.
+function sessionOwnerMachine(sid: string): string {
+  const dot = sid.lastIndexOf(".");
+  return dot === -1 ? "" : sid.slice(dot + 1);
+}
+
 async function startHttpServer() {
   const host = process.env.TD_MCP_HOST || "127.0.0.1";
   const port = Number(process.env.TD_MCP_PORT || process.env.PORT || 8788);
@@ -1985,12 +2117,49 @@ async function startHttpServer() {
         return;
       }
 
+      // RFC 9728 protected-resource metadata so OAuth clients discover Auth0.
+      // Only advertised when OAuth is enforced. Some clients append the resource
+      // path to the well-known URL, so match both.
+      if (
+        isOAuthEnabled() &&
+        req.method === "GET" &&
+        (url.pathname === "/.well-known/oauth-protected-resource" ||
+          url.pathname === `/.well-known/oauth-protected-resource${mcpPath}`)
+      ) {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(protectedResourceMetadata(req, mcpPath)));
+        return;
+      }
+
       if (url.pathname !== mcpPath) {
         res.writeHead(404, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: "Not found", hint: `MCP endpoint is ${mcpPath}` }));
         return;
       }
 
+      // OAuth resource-server enforcement (only when TD_MCP_AUTH=oauth). When
+      // disabled this is a no-op so local/trusted-network usage is unchanged.
+      let resolvedApiKey: string | null = null;
+      let resolvedToken: string | null = null;
+      if (isOAuthEnabled()) {
+        const auth = await authenticate(req);
+        if (!auth.ok) {
+          res.writeHead(auth.status, {
+            "content-type": "application/json",
+            "www-authenticate": wwwAuthenticate(req, { error: auth.error, description: auth.description }),
+          });
+          res.end(JSON.stringify({ error: auth.error, error_description: auth.description }));
+          return;
+        }
+        resolvedToken = auth.token;
+        resolvedApiKey = await exchangeOAuthTokenForApiKey(auth.token);
+        if (!resolvedApiKey) {
+          res.writeHead(403, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "no_team", error_description: "No TestDriver team is linked to this account" }));
+          return;
+        }
+      }
+
       const sessionId = req.headers["mcp-session-id"];
       const sid = Array.isArray(sessionId) ? sessionId[0] : sessionId;
 
@@ -2003,6 +2172,15 @@ async function startHttpServer() {
       // A brand-new session: only an `initialize` request may create one.
       if (!connection) {
         if (sid) {
+          // The session lives on another Fly machine: ask Fly's proxy to replay
+          // this request there instead of 404ing (which would force a new
+          // sandbox). Only when the owner is a *different* known machine.
+          const owner = sessionOwnerMachine(sid);
+          if (FLY_MACHINE_ID && owner && owner !== FLY_MACHINE_ID) {
+            res.writeHead(409, { "fly-replay": `instance=${owner}` });
+            res.end();
+            return;
+          }
           // Client presented a session id we don't know — it was torn down or is
           // stale. 404 so the client re-initializes (matches SDK stateful mode).
           res.writeHead(404, { "content-type": "application/json" });
@@ -2017,9 +2195,21 @@ async function startHttpServer() {
 
         // Mint an isolated context + a server bound to it + a transport.
         const ctx = core.createIsolatedContext();
+        // Seed the per-session team key so session_start provisions under the
+        // caller's own team (hosted OAuth mode). Falls back to env when unset.
+        if (resolvedApiKey) {
+          ctx.adapter.apiKey = resolvedApiKey;
+        }
+        // Keep the caller's Bearer so data tools can call the backend REST API as
+        // the authenticated user.
+        if (resolvedToken) {
+          ctx.adapter.oauthToken = resolvedToken;
+        }
         const mcpServer = buildServer();
         const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
+          // Tag the owning machine into the id (multi-machine only) so later
+          // requests can be replayed here via `fly-replay`.
+          sessionIdGenerator: () => (FLY_MACHINE_ID ? `${randomUUID()}.${FLY_MACHINE_ID}` : randomUUID()),
           onsessioninitialized: (newId: string) => {
             connections.set(newId, { transport, server: mcpServer, ctx });
             logger.info("http: MCP session initialized", { sessionId: newId, activeSessions: connections.size });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testdriverai/agent",
-  "version": "7.11.146-canary",
+  "version": "7.11.147-test",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",