@silver886/mcp-proxy 0.2.4 → 0.2.6

package/README.md

@@ -106,7 +106,8 @@ single-proxy, in line with MCP's one-server-one-client model.)
 2. Agent calls the `configure` tool. Proxy spawns a Node wrapper that owns
    a `cloudflared` quick tunnel pointing at a local pairing HTTP server.
    That HTTP server serves both the setup page (GET /) and the pairing API
-   (POST /pair/forward, POST /pair/complete) on the same origin.
+   (POST /pair/list-servers, POST /pair/discover, POST /pair/complete) on
+   the same origin.
 3. Wrapper prints the tunnel URL. Proxy mints a bearer token and emits a
    setup URL — `<tunnel>/#token=<token>`. Token rides in the URL fragment
    so it never appears in server access logs or Referer headers.

package/dist/host/agent.d.ts

@@ -19,4 +19,6 @@ export declare class HostAgent {
     private authorized;
     private handleMcpPost;
     private handleSse;
+    private handleAdminRestart;
+    private restartServer;
 }

package/dist/host/agent.js

@@ -29,25 +29,63 @@ class HostAgent {
     boundPort;
     constructor(configPath, timeout, overrides) {
         const raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
-        this.config = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
         this.timeout = timeout;
         this.authToken = (0, node_crypto_1.randomBytes)(32).toString("base64url"); // 256-bit token
-        this.boundHost = overrides?.host ?? this.config.host ?? protocol_js_1.DEFAULT_HOST;
-        // port 0 = let the OS pick. Resolved to the real bound port in start().
-        this.boundPort = overrides?.port ?? this.config.port ?? protocol_js_1.DEFAULT_PORT;
-        // Reject server names that the proxy/page would silently drop later.
-        // Authoritative at config-load time so misnamed servers surface as a
-        // startup error instead of disappearing during discovery.
+        // Single boundary-time validation pass: server-name policy, per-entry
+        // shape, and top-level host/port. Documented defaults (args=[]) are
+        // installed by normalizeServerConfig so downstream consumers can trust
+        // the ServerConfig contract instead of re-checking shapes — without
+        // this, omitting `args` (legal per README) crashes McpSession deep
+        // inside `args.join(" ")`. All reasons are accumulated so a broken
+        // file surfaces a complete diff to fix in one error message rather
+        // than one-issue-per-restart.
         const invalid = [];
-        for (const name of Object.keys(this.config.servers)) {
-            const reason = (0, protocol_js_1.validateServerName)(name);
-            if (reason)
-                invalid.push(`  - "${name}": ${reason}`);
+        const servers = {};
+        if (!parsed.servers || typeof parsed.servers !== "object" || Array.isArray(parsed.servers)) {
+            invalid.push(`  - "servers": must be an object map of name to config`);
+        }
+        else {
+            const rawServers = parsed.servers;
+            if (Object.keys(rawServers).length === 0) {
+                invalid.push(`  - "servers": at least one server must be declared`);
+            }
+            for (const [name, entry] of Object.entries(rawServers)) {
+                const nameReason = (0, protocol_js_1.validateServerName)(name);
+                if (nameReason)
+                    invalid.push(`  - "${name}": ${nameReason}`);
+                const result = (0, protocol_js_1.normalizeServerConfig)(entry);
+                if (!result.ok) {
+                    for (const reason of result.reasons)
+                        invalid.push(`  - "${name}": ${reason}`);
+                }
+                else if (!nameReason) {
+                    servers[name] = result.config;
+                }
+            }
+        }
+        if (parsed.host !== undefined && typeof parsed.host !== "string") {
+            invalid.push(`  - "host": must be a string (default: ${protocol_js_1.DEFAULT_HOST})`);
+        }
+        if (parsed.port !== undefined
+            && (typeof parsed.port !== "number"
+                || !Number.isInteger(parsed.port)
+                || parsed.port < 0
+                || parsed.port > 65535)) {
+            invalid.push(`  - "port": must be an integer 0–65535 (default: ${protocol_js_1.DEFAULT_PORT})`);
         }
         if (invalid.length > 0) {
-            throw new Error(`Invalid server name(s) in ${configPath}:\n${invalid.join("\n")}\n` +
-                `Rename the entries in config.json so they match the policy.`);
+            throw new Error(`Invalid host config in ${configPath}:\n${invalid.join("\n")}\n` +
+                `Fix the entries in config.json so they match the documented schema.`);
         }
+        this.config = {
+            servers,
+            host: typeof parsed.host === "string" ? parsed.host : undefined,
+            port: typeof parsed.port === "number" ? parsed.port : undefined,
+        };
+        this.boundHost = overrides?.host ?? this.config.host ?? protocol_js_1.DEFAULT_HOST;
+        // port 0 = let the OS pick. Resolved to the real bound port in start().
+        this.boundPort = overrides?.port ?? this.config.port ?? protocol_js_1.DEFAULT_PORT;
     }
     get port() {
         return this.boundPort;
@@ -148,6 +186,15 @@ class HostAgent {
             }));
             return;
         }
+        if (pathname === "/admin/restart") {
+            if (req.method !== "POST") {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            await this.handleAdminRestart(req, res);
+            return;
+        }
         const match = pathname.match(/^\/servers\/([^/]+)$/);
         if (!match) {
             res.writeHead(404, { "Content-Type": "application/json" });
@@ -200,19 +247,28 @@ class HostAgent {
     async handleMcpPost(req, res, serverName, serverConfig) {
         const body = await (0, protocol_js_1.readBody)(req);
         const headerSessionId = req.headers["mcp-session-id"];
-        // Peek the JSON-RPC method without consuming the body. Only `initialize`
-        // may run without an existing session — anything else against an
-        // unknown id is stale (post-GC, post-restart) or wrong, and silently
-        // spawning a fresh uninitialized child for it would violate the MCP
-        // handshake.
-        let method;
+        // Parse once at the HTTP boundary. The host is the JSON-RPC endpoint
+        // from the proxy's perspective, so a malformed body must surface as a
+        // spec-compliant parse-error response with id:null — not get forwarded
+        // to the child as a notification. Without this gate the body falls
+        // through sendRequest's `id === undefined` branch (notification path),
+        // garbage hits stdin, the caller gets a misleading 202, and the
+        // child's parse-error reply arrives with id:null and is dropped as an
+        // orphan — guaranteeing a silent timeout on the proxy.
+        let parsedBody;
         try {
-            method = JSON.parse(body).method;
+            parsedBody = JSON.parse(body);
         }
         catch {
-            // Unparseable body falls through as non-initialize → 404 below.
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.PARSE_ERROR, undefined, null));
+            return;
         }
-        const isInitialize = method === "initialize";
+        // Only `initialize` may run without an existing session — anything
+        // else against an unknown id is stale (post-GC, post-restart) or
+        // wrong, and silently spawning a fresh uninitialized child for it
+        // would violate the MCP handshake.
+        const isInitialize = parsedBody.method === "initialize";
         let existing;
         if (headerSessionId) {
             existing = this.sessions.get(headerSessionId);
@@ -310,5 +366,62 @@ class HostAgent {
         }, constants_js_1.SSE_DRAIN_INTERVAL_MS);
         req.on("close", () => clearInterval(interval));
     }
+    // POST /admin/restart  body: { "server": "<name>" }
+    // Kills every live session for that server. The next forward from the
+    // proxy will see a 404 (because the session id is gone from the map),
+    // re-`initialize` via the proxy's existing stale-session recovery, and
+    // spawn a fresh child. The host doesn't need to know about hosts/aliases
+    // — it trusts the bearer for scoping.
+    async handleAdminRestart(req, res) {
+        const body = await (0, protocol_js_1.readBody)(req);
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "server is required" }));
+            return;
+        }
+        const serverName = parsed.server;
+        if (typeof serverName !== "string" || serverName.length === 0) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "server is required" }));
+            return;
+        }
+        if (!this.config.servers[serverName]) {
+            // Mirror the /servers/:name miss shape (agent.ts:218-221) so the proxy
+            // can forward `available` straight into the LLM-facing error.
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: `Unknown server: ${serverName}`,
+                available: Object.keys(this.config.servers),
+            }));
+            return;
+        }
+        const killed = this.restartServer(serverName);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, killed }));
+    }
+    // Destroy + drop every live session belonging to `name`. killed=0 is
+    // success — the post-condition (no live session for this server) is met
+    // either way. McpSession.destroy synchronously fails pending requests
+    // with PROCESS_EXITED (so in-flight forwards resolve immediately rather
+    // than waiting on the per-request timeout) and tree-kills the whole
+    // process group (so `shell: true` / `npx` configs don't leave the real
+    // MCP server alive as a grandchild).
+    restartServer(name) {
+        let killed = 0;
+        for (const [id, session] of this.sessions) {
+            if (session.serverName !== name)
+                continue;
+            session.destroy();
+            this.sessions.delete(id);
+            killed++;
+        }
+        if (killed > 0)
+            console.log(`[${name}] Restarted: ${killed} session(s) destroyed`);
+        return killed;
+    }
 }
 exports.HostAgent = HostAgent;

package/dist/host/session.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpSession = void 0;
 const node_child_process_1 = require("node:child_process");
+const tree_kill_1 = __importDefault(require("tree-kill"));
 const protocol_js_1 = require("../shared/protocol.js");
 const constants_js_1 = require("./constants.js");
 // One McpSession owns a single MCP server child process and matches its
@@ -193,12 +197,37 @@ class McpSession {
     get isAlive() {
         return !this.destroyed;
     }
+    // Idempotent. Three steps, in order:
+    //
+    //   1. Mark destroyed BEFORE failing pending so any synchronous
+    //      sendRequest racing on another tick short-circuits to
+    //      PROCESS_NOT_RUNNING instead of registering into a map we're
+    //      about to drain.
+    //   2. failPending synchronously: don't wait for the child's 'exit'
+    //      handler. A child that ignores SIGTERM (or a shell wrapper that
+    //      swallows it) would otherwise leave callers waiting the full
+    //      per-request timeout. The 'exit' handler's later failPending
+    //      becomes a no-op against the now-empty map.
+    //   3. tree-kill the WHOLE process group, not just the direct child.
+    //      Documented configs use `shell: true` / `npx`, where the real MCP
+    //      server is a grandchild of /bin/sh; a bare process.kill() leaves
+    //      it alive after the shell exits, which would silently break
+    //      restart_server's contract ("session destroyed" but the wedged
+    //      child is still answering on stdin somewhere).
     destroy() {
         if (this.destroyed)
             return;
         this.destroyed = true;
-        if (!this.process.killed)
-            this.process.kill();
+        this.failPending(protocol_js_1.ErrorCode.PROCESS_EXITED, "session destroyed");
+        if (!this.process.killed && this.process.pid !== undefined) {
+            // Default signal is SIGTERM; tree-kill walks ps/taskkill on
+            // POSIX/Windows and signals every descendant. Errors here mean the
+            // tree is already gone (race with natural exit) — best-effort.
+            (0, tree_kill_1.default)(this.process.pid, (err) => {
+                if (err)
+                    console.error(`[${this.name}] tree-kill failed: ${err.message}`);
+            });
+        }
     }
 }
 exports.McpSession = McpSession;

package/dist/proxy/core/constants.d.ts

@@ -6,8 +6,12 @@ export declare const UPSTREAM_REQUEST_TIMEOUT_MS = 120000;
 export declare const DISCOVERY_FETCH_TIMEOUT_MS = 15000;
 export declare const TOOL_FORWARD_TIMEOUT_MS: number;
 export declare const SESSION_DELETE_TIMEOUT_MS = 5000;
+export declare const PAIRING_HEADERS_TIMEOUT_MS = 30000;
+export declare const PAIRING_REQUEST_TIMEOUT_MS = 60000;
 export declare const SSE_BACKOFF_INITIAL_MS = 500;
 export declare const SSE_BACKOFF_MAX_MS = 10000;
 export declare const SSE_CONNECT_TIMEOUT_MS = 15000;
 export declare const CONFIGURE_TOOL: Tool;
 export declare const CONFIGURE_PROMPT: Prompt;
+export declare const RESTART_SERVER_TOOL: Tool;
+export declare const RESTART_SERVER_PROMPT: Prompt;

package/dist/proxy/core/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIGURE_PROMPT = exports.CONFIGURE_TOOL = exports.SSE_CONNECT_TIMEOUT_MS = exports.SSE_BACKOFF_MAX_MS = exports.SSE_BACKOFF_INITIAL_MS = exports.SESSION_DELETE_TIMEOUT_MS = exports.TOOL_FORWARD_TIMEOUT_MS = exports.DISCOVERY_FETCH_TIMEOUT_MS = exports.UPSTREAM_REQUEST_TIMEOUT_MS = exports.PAIRING_WINDOW_MS = exports.TUNNEL_STARTUP_TIMEOUT_MS = exports.TOOL_SEPARATOR = void 0;
+exports.RESTART_SERVER_PROMPT = exports.RESTART_SERVER_TOOL = exports.CONFIGURE_PROMPT = exports.CONFIGURE_TOOL = exports.SSE_CONNECT_TIMEOUT_MS = exports.SSE_BACKOFF_MAX_MS = exports.SSE_BACKOFF_INITIAL_MS = exports.PAIRING_REQUEST_TIMEOUT_MS = exports.PAIRING_HEADERS_TIMEOUT_MS = exports.SESSION_DELETE_TIMEOUT_MS = exports.TOOL_FORWARD_TIMEOUT_MS = exports.DISCOVERY_FETCH_TIMEOUT_MS = exports.UPSTREAM_REQUEST_TIMEOUT_MS = exports.PAIRING_WINDOW_MS = exports.TUNNEL_STARTUP_TIMEOUT_MS = exports.TOOL_SEPARATOR = void 0;
 const protocol_js_1 = require("../../shared/protocol.js");
 exports.TOOL_SEPARATOR = protocol_js_1.TOOL_NAME_SEPARATOR;
 // Pairing-tunnel + bridging budgets.
@@ -15,6 +15,13 @@ exports.UPSTREAM_REQUEST_TIMEOUT_MS = 120_000; // server→client bridge
 exports.DISCOVERY_FETCH_TIMEOUT_MS = 15_000;
 exports.TOOL_FORWARD_TIMEOUT_MS = 5 * 60 * 1000;
 exports.SESSION_DELETE_TIMEOUT_MS = 5_000;
+// Pairing HTTP server per-request budgets. Pairing payloads are small JSON
+// blobs (host creds, selected servers/tools), so a slow header or body
+// phase is broken or hostile rather than legitimate. Bounding both prevents
+// a slow upload from outliving PAIRING_WINDOW_MS via Node's defaults
+// (headersTimeout 60s, requestTimeout 5min).
+exports.PAIRING_HEADERS_TIMEOUT_MS = 30_000;
+exports.PAIRING_REQUEST_TIMEOUT_MS = 60_000;
 exports.SSE_BACKOFF_INITIAL_MS = 500;
 exports.SSE_BACKOFF_MAX_MS = 10_000;
 // Bound the connect+headers phase only. A blackholed tunnel would otherwise
@@ -37,3 +44,41 @@ exports.CONFIGURE_PROMPT = {
     name: "configure",
     description: "Set up or reconfigure the MCP proxy connection.",
 };
+// Local tool: kill the host's child process for a wedged MCP server so the
+// next forward re-spawns it. The description teaches the LLM how to format
+// the `tool` argument, since the form it sees in its catalog (wrapped by
+// its MCP client as `mcp__<alias>__...`) is NOT the form the proxy parses.
+exports.RESTART_SERVER_TOOL = {
+    name: "restart_server",
+    description: "Restart a wedged MCP server (kills the host's child process; next call respawns it). "
+        + "Pass `tool` as the proxy-internal name `<host>__<server>__<tool>`. "
+        + "If your tool catalog shows it as `mcp__<alias>__<host>__<server>__<tool>`, strip the `mcp__<alias>__` prefix first. "
+        + "Or pass `host` and `server` directly (visible in every tool's description as `[<host>/<server>]`).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            tool: {
+                type: "string",
+                description: "Proxy-internal tool name <host>__<server>__<tool>. Strip any mcp__<alias>__ wrapper your client adds.",
+            },
+            host: { type: "string", description: "Host id (alternative to tool)." },
+            server: { type: "string", description: "Server name (alternative to tool)." },
+        },
+    },
+};
+// Local prompt counterpart. Same handler, same parser — the prompt is just
+// another entry point so an operator can drive a restart from the picker
+// without round-tripping through the LLM's planner.
+exports.RESTART_SERVER_PROMPT = {
+    name: "restart_server",
+    description: "Restart a wedged MCP server (kills the host's child; next call respawns).",
+    arguments: [
+        {
+            name: "tool",
+            description: "Proxy-internal tool name <host>__<server>__<tool>. Strip any mcp__<alias>__ wrapper your client adds.",
+            required: false,
+        },
+        { name: "host", description: "Host id (alternative to tool).", required: false },
+        { name: "server", description: "Server name (alternative to tool).", required: false },
+    ],
+};

package/dist/proxy/discovery/client.js

@@ -13,6 +13,17 @@ exports.listHostServers = listHostServers;
 const protocol_js_1 = require("../../shared/protocol.js");
 const constants_js_1 = require("../core/constants.js");
 const fetch_timeout_js_1 = require("../core/fetch-timeout.js");
+// Discovery helpers. List calls (tools/prompts/resources/templates)
+// distinguish METHOD_NOT_FOUND ("feature absent" → []) from any other
+// failure (transport blip, JSON-RPC error, malformed body → throw). The
+// caller decides whether to preserve cached state, mark a per-capability
+// retry flag, or fail outright. Every fetch is wrapped in
+// DISCOVERY_FETCH_TIMEOUT_MS so a host that accepts the connection then
+// hangs can't pin the proxy.
+// JSON-RPC METHOD_NOT_FOUND — what an MCP server returns when it doesn't
+// support a capability. Treated as "feature absent" (empty list), distinct
+// from a transport blip which the strict variants surface as a throw.
+const METHOD_NOT_FOUND = -32601;
 async function initializeServer(targetUrl, baseHeaders, name, clientCapabilities, clientInfo) {
     const resp = await fetch(targetUrl, {
         method: "POST",
@@ -81,14 +92,13 @@ async function fetchTools(targetUrl, headers, name) {
         throw new Error(`tools/list returned malformed JSON: ${err.message}`);
     }
     const error = data.error;
-    if (error)
+    if (error) {
+        if (error.code === METHOD_NOT_FOUND)
+            return [];
         throw new Error(`tools/list error: ${error.message ?? JSON.stringify(error)}`);
+    }
     return extractListField(data, "tools/list", "tools");
 }
-// JSON-RPC METHOD_NOT_FOUND — what an MCP server returns when it doesn't
-// support a capability. Treated as "feature absent" (empty list), distinct
-// from a transport blip which the strict variants surface as a throw.
-const METHOD_NOT_FOUND = -32601;
 // Run a tools/prompts/resources-style list call against the upstream and
 // extract the list field. Throws on any transport, parse, or JSON-RPC
 // failure other than METHOD_NOT_FOUND, which collapses to []. Callers
@@ -148,12 +158,15 @@ class DiscoveryError extends Error {
 }
 exports.DiscoveryError = DiscoveryError;
 // Single source of truth for the per-server MCP handshake: initialize →
-// notifications/initialized → tools/list (required) → prompts / resources /
-// templates (each optional, recorded as pending on failure). Used by both
-// the runtime discovery path and the pairing-mediated discovery endpoint
-// so the browser sees the same capability set the proxy will see at
-// runtime — including using the real MCP client's capabilities/clientInfo
-// rather than synthetic browser values.
+// notifications/initialized → tools / prompts / resources / templates
+// (each optional — METHOD_NOT_FOUND collapses to [], other failures on
+// prompts/resources/templates are recorded as pending; tools failures
+// other than METHOD_NOT_FOUND are still fatal because tools/list is the
+// canonical "is this server alive" probe). Used by both the runtime
+// discovery path and the pairing-mediated discovery endpoint so the
+// browser sees the same capability set the proxy will see at runtime —
+// including using the real MCP client's capabilities/clientInfo rather
+// than synthetic browser values.
 async function discoverServerCapabilities(targetUrl, baseHeaders, name, clientCapabilities, clientInfo, log) {
     let sessionId;
     try {

package/dist/proxy/pairing/config.js

@@ -67,11 +67,12 @@ function validatePairingConfig(cfg) {
     // server-level allow list never triggered. Catching it here keeps the
     // invariant on the way IN to ProxyServer state.
     //
-    // Server names may themselves contain `__`, so we don't `split` — we
-    // take the prefix before the FIRST `__` as the hostId and require the
-    // remainder (the serverName) to be non-empty so a malformed entry like
-    // `host__` doesn't sneak through as a valid-looking allowlist line that
-    // can never match any real server.
+    // Mirrors the indexOf form used by the selectedTools parser below for
+    // consistency. validateServerName forbids `__` in both the hostId and
+    // the serverName, so a single split on the FIRST `__` is sound; the
+    // remainder must be non-empty so a malformed entry like `host__`
+    // doesn't sneak through as a valid-looking allowlist line that can
+    // never match any real server.
     const validHostIds = new Set(validatedHosts.map((h) => h.id));
     if (cfg.selectedServers) {
         for (const entry of cfg.selectedServers) {
@@ -95,12 +96,13 @@ function validatePairingConfig(cfg) {
     // actually carry a tool name: an entry whose server prefix isn't in
     // selectedServers (when defined) — or whose hostId isn't a known host
     // (when selectedServers is omitted) — is unreachable noise that hides
-    // bugs in the UI or stale configs. Tool/server names may themselves
-    // contain `__`, so we prefix-match the allowed scope rather than
-    // splitting on the separator. Shape is enforced separately by requiring
-    // at least two `__` occurrences — the prefix-match alone degraded to a
-    // hostId-only check when `selectedServers` was omitted, letting entries
-    // like `host__bogus` survive without a tool segment.
+    // bugs in the UI or stale configs. validateServerName forbids `__` in
+    // host id and server name, but tool names CAN contain `__`, so we
+    // prefix-match the allowed scope rather than splitting on the separator.
+    // Shape is enforced separately by requiring at least two `__` occurrences
+    // — the prefix-match alone degraded to a hostId-only check when
+    // `selectedServers` was omitted, letting entries like `host__bogus`
+    // survive without a tool segment.
     if (cfg.selectedTools) {
         const allowedServerPrefixes = cfg.selectedServers
             ? cfg.selectedServers.map((s) => `${s}${constants_js_1.TOOL_SEPARATOR}`)

package/dist/proxy/pairing/controller.d.ts

@@ -8,12 +8,15 @@ export declare class PairingController {
     private readonly log;
     private readonly sendNotification;
     private pairing;
+    private configureInflight;
     constructor(state: ProxyState, runner: DiscoveryRunner, bridge: UpstreamBridge, log: (line: string) => void, sendNotification: (method: string) => void);
     handleConfigure(): Promise<string>;
+    private doConfigure;
     teardownPairing(): void;
     private validateHostCreds;
     private handleListServers;
     private handleDiscover;
     private handleComplete;
+    private notifyAllListsChanged;
     closeAllSessions(): Promise<void>;
 }

package/dist/proxy/pairing/controller.js

@@ -22,6 +22,13 @@ class PairingController {
     log;
     sendNotification;
     pairing = null;
+    // Single-flight gate for handleConfigure. Without it, two `configure`
+    // calls landing in the same event-loop window both observe `this.pairing`
+    // as null, both spawn an HTTP server + cloudflared subprocess, and the
+    // second's assignment to `this.pairing` orphans the first. The orphan's
+    // expiryTimer would then later call teardownPairing() and tear down the
+    // wrong (active) pairing, killing a working setup mid-session.
+    configureInflight = null;
     constructor(state, runner, bridge, log, sendNotification) {
         this.state = state;
         this.runner = runner;
@@ -29,7 +36,15 @@ class PairingController {
         this.log = log;
         this.sendNotification = sendNotification;
     }
-    async handleConfigure() {
+    handleConfigure() {
+        if (this.configureInflight)
+            return this.configureInflight;
+        this.configureInflight = this.doConfigure().finally(() => {
+            this.configureInflight = null;
+        });
+        return this.configureInflight;
+    }
+    async doConfigure() {
         this.teardownPairing();
         const bearer = (0, node_crypto_1.randomBytes)(32).toString("base64url");
         const http = new http_js_1.PairingHttpServer(bearer, {
@@ -238,8 +253,9 @@ class PairingController {
         // to "every advertised host must land at least one server".
         const missing = [];
         if (cfg.selectedServers) {
-            // Server names may contain `__`, so prefix-match on the FIRST `__`
-            // — same parsing rule used in validatePairingConfig.
+            // validateServerName forbids `__` in host id and server name, so
+            // a single split on the FIRST `__` is sound — same parsing rule
+            // used in validatePairingConfig.
             for (const key of cfg.selectedServers) {
                 const sep = key.indexOf("__");
                 if (sep <= 0)
@@ -257,6 +273,22 @@ class PairingController {
                     missing.push(`${host.config.id} (no servers)`);
             }
         }
+        // selectedTools entries are validated structurally by validatePairingConfig,
+        // but their existence on the wire can only be checked after discovery has
+        // populated state.toolRoute. The browser path can't produce stale entries
+        // (the UI builds selectedTools from the just-discovered set), but a direct
+        // caller of /pair/complete can — and getFilteredTools silently drops any
+        // entry whose key isn't in toolRoute, leaving the proxy paired-but-empty
+        // for tools with no error surfaced. Treat stale entries the same as
+        // missing servers: roll back to the previous pairing (or refuse, on
+        // first-time pair) so the operator gets a real failure signal instead of
+        // a cheerful ok on a config that won't expose any tools.
+        if (cfg.selectedTools) {
+            for (const key of cfg.selectedTools) {
+                if (!this.state.toolRoute.has(key))
+                    missing.push(key);
+            }
+        }
         if (missing.length > 0) {
             // Cap the detail string so a wildly broken submit doesn't produce a
             // multi-kilobyte error body; the operator only needs a few names to
@@ -269,6 +301,12 @@ class PairingController {
                 this.log(`  New pairing missing servers (${detail}); restoring previous pairing`);
                 this.state.installConfig(previousConfig, previousHosts);
                 await this.runner.discoverServers();
+                // installConfig replaced toolRoute / promptRoute / resources between
+                // the success-path notify (only fires when missing.length === 0) and
+                // here, so an agent that polled tools/list during the new pairing's
+                // discovery may be holding a partial snapshot that no longer matches
+                // the restored routes. Notify list_changed so it re-fetches.
+                this.notifyAllListsChanged();
                 return {
                     ok: false,
                     error: `Discovery did not complete for: ${detail}. The previous pairing has been restored — verify host reachability and retry.`,
@@ -279,6 +317,10 @@ class PairingController {
             // so the next configure call starts fresh).
             this.log(`  New pairing missing servers (${detail}) and no prior config to restore; reverting to unconfigured`);
             this.state.config = null;
+            // Same notify rationale as the rollback branch above: a polling agent
+            // may have grabbed partial-new routes during discovery; tell it to
+            // re-fetch and find an empty unconfigured set.
+            this.notifyAllListsChanged();
             return {
                 ok: false,
                 error: `Discovery did not complete for: ${detail}. Verify host reachability and retry.`,
@@ -289,16 +331,27 @@ class PairingController {
         // Discovery already populated the aggregated lists. Notify the agent
         // so it re-fetches tools/prompts/resources instead of trusting any
         // cached empty lists from before pairing.
-        this.sendNotification("notifications/tools/list_changed");
-        this.sendNotification("notifications/prompts/list_changed");
-        this.sendNotification("notifications/resources/list_changed");
+        this.notifyAllListsChanged();
         // Defer pairing teardown until /pair/complete's response body has
         // actually drained to the client — a fixed timer races slow clients
         // (mobile data, congested tunnel) and they see a dropped connection
         // on a successful pair.
         return { ok: true, afterFlush: () => this.teardownPairing() };
     }
+    notifyAllListsChanged() {
+        this.sendNotification("notifications/tools/list_changed");
+        this.sendNotification("notifications/prompts/list_changed");
+        this.sendNotification("notifications/resources/list_changed");
+    }
     async closeAllSessions() {
+        // Bump the supersession token before any await so an in-flight forwarder
+        // request that resolves during teardown sees a stale generation and
+        // refuses to write its response. Without this, a fetch completing during
+        // bridge.clear / DELETE awaits emits onto stdout against a pairing that
+        // no longer exists. installConfig() bumps again on the way in; the
+        // double-bump is harmless because the token is only used for equality
+        // comparison.
+        this.state.configGeneration++;
         // Tear down SSE listeners first so loops don't reconnect after DELETE.
         for (const host of this.state.hosts.values()) {
             for (const ctrl of host.sseControllers.values())

package/dist/proxy/pairing/http.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PairingHttpServer = void 0;
 const node_crypto_1 = require("node:crypto");
 const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
 const static_assets_js_1 = require("./static-assets.js");
 class PairingHttpServer {
     bearer;
@@ -17,6 +18,11 @@ class PairingHttpServer {
     listen() {
         return new Promise((resolveP, rejectP) => {
             const srv = (0, protocol_js_1.createServer)((req, res) => this.handle(req, res));
+            // Bound the header + body phases so a slow upload can't drag past
+            // PAIRING_WINDOW_MS. Node defaults (60s / 5min) are too generous for
+            // small JSON pairing payloads.
+            srv.headersTimeout = constants_js_1.PAIRING_HEADERS_TIMEOUT_MS;
+            srv.requestTimeout = constants_js_1.PAIRING_REQUEST_TIMEOUT_MS;
             srv.once("error", rejectP);
             srv.listen(0, "127.0.0.1", () => {
                 const addr = srv.address();
@@ -32,6 +38,11 @@ class PairingHttpServer {
     close() {
         if (!this.server)
             return;
+        // server.close() alone only refuses new connections; idle keep-alive
+        // sockets and any in-flight request body would otherwise outlive the
+        // pairing window. closeAllConnections() (Node ≥18.2) hard-drops them
+        // so teardown is bounded by the window, not by the slowest client.
+        this.server.closeAllConnections();
         this.server.close();
         this.server = null;
     }