pi-mcp-extension 1.9.0 → 1.9.2

package/README.md

@@ -9,19 +9,20 @@
 
 ## Features
 
-- **Multi-transport** — `stdio` subprocesses, `streamable-http`, and legacy `sse` out of the box
+- **Multi-transport** — `stdio` subprocesses, `streamable-http` (including `"http"` and URL-only shorthand), and legacy `sse` out of the box
 - **Auto-discovery** — Paginated `tools/list` with cursor following (MCP 2025-03-26 spec)
 - **Live tool refresh** — `notifications/tools/list_changed` triggers re-discovery without restart
 - **Clean cancellation** — `AbortSignal` propagation via `notifications/cancelled`
-- **Smart reconnection** — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries
+- **Smart reconnection** — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries, and automatic recovery when a server transport closes unexpectedly
 - **Health checks** — Opt-in periodic pings to detect stale connections
-- **Safe process lifecycle** — PID tracking with safety-net `SIGKILL` for orphaned subprocesses
+- **Safe process lifecycle** — Child PID tracking (`StdioClientTransport.pid`) with safety-net `SIGKILL` for orphaned subprocesses
 - **Stable tool names** — Sanitized, collision-avoiding names (max 64 chars) that stay constant across reconnects
 - **No tool churn** — Activate/deactivate pattern ensures tools don't flicker during reconnection
-- **Global + project config** — Layered config (project overrides global) with per-server tuning
-- **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
+- **Layered config & trust boundary** — Global `<agent dir>/mcp.json`, project `.pi/mcp.json` (loaded only in trusted projects via `ctx.isProjectTrusted()`), and Pi 1.x extension-registered servers (`pi.registerMcpServer()`)
+- **Rich tool results & annotations** — MCP `image` content passthrough (`ImageContent`), plus `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
+- **On-demand agent tools & commands** — `mcp_status` and `mcp_connect` agent tools plus `/mcp`, `/mcp:start`, `/mcp:stop`, and `/mcp:auth` slash commands with server-name autocomplete
 - **Structured error handling** — Distinct error codes for config, connection, protocol, and tool-level failures
-- **OAuth 2.1** — Browser authorization with PKCE, protected-resource discovery, token refresh, and secure local persistence
+- **OAuth 2.1** — Browser and headless/SSH authorization with PKCE, protected-resource discovery, Dynamic Client Registration, startup prompts for eager servers, cross-process lock recovery, token refresh, and secure local persistence (see [OAUTH.md](./OAUTH.md))
 
 ## Installation
 
@@ -42,7 +43,16 @@ pi -e npm:pi-mcp-extension
    pi install npm:pi-mcp-extension
    ```
 
-2. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
+2. *(Pi 1.x)* Disable Pi's built-in `mcp` extension so Pi does not warn that both extensions are enabled at the same time — either run `pi config` and uncheck `mcp` under **Built-in extensions**, or add `"extensions": ["-builtin:mcp"]` to `~/.pi/agent/settings.json`:
+   ```jsonc
+   {
+     "extensions": [
+       "-builtin:mcp"
+     ]
+   }
+   ```
+
+3. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
    ```jsonc
    {
      "mcpServers": {
@@ -55,16 +65,17 @@ pi -e npm:pi-mcp-extension
    }
    ```
 
-3. Start Pi — your MCP tools are ready. Use `/mcp` to check server status.
+4. Start Pi — your MCP tools are ready. Use `/mcp` to check server status.
 
 ## Configuration
 
-Config files are loaded from two locations. **Project config overrides global config** via shallow merge (server-level replacement).
+Servers can be configured via JSON files or registered programmatically by other Pi 1.x extensions:
 
-| Location | Scope |
+| Source | Precedence & Scope |
 |---|---|
-| `~/.pi/agent/mcp.json` | Global — applies to all projects (honors `$PI_CODING_AGENT_DIR` when set: `<agent dir>/mcp.json`) |
-| `.pi/mcp.json` | Project — overrides global per-server |
+| `.pi/mcp.json` | **Highest** — Project-level overrides per server and per explicitly stated setting. Loaded on `session_start` **only when the project is trusted** (`ctx.isProjectTrusted()`); never read at bootstrap or in untrusted projects. |
+| `~/.pi/agent/mcp.json` | **Global** — Applies to all projects (honors `$PI_CODING_AGENT_DIR` with `~` expansion when set: `<agent dir>/mcp.json`). |
+| `pi.registerMcpServer()` | **Extension-registered** — Discovered via `pi.getMcpServers()` and updated live on `mcp_servers_change` events when replacing `builtin:mcp`. Any server with the same name in `mcp.json` takes precedence. |
 
 ### Full Example
 
@@ -87,8 +98,7 @@ Config files are loaded from two locations. **Project config overrides global co
       "lifecycle": "eager"
     },
     "deepsource": {
-      "transport": "streamable-http",
-      "url": "https://mcp.deepsource.io/mcp",
+      "url": "https://mcp.deepsource.io/mcp", // "transport" defaults to "streamable-http" when "url" is set
       "lifecycle": "eager"
     },
 
@@ -126,6 +136,8 @@ Config files are loaded from two locations. **Project config overrides global co
 
 ### Global Settings
 
+In project-level `.pi/mcp.json`, `settings` keys carry no defaults — only the keys explicitly stated in the project file override global settings.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `toolPrefix` | `string` | `"mcp"` | Prefix for registered tools: `<prefix>_<server>_<tool>`. Must match `^[a-zA-Z][a-zA-Z0-9_]*$`. |
@@ -134,28 +146,32 @@ Config files are loaded from two locations. **Project config overrides global co
 
 ### Per-Server Config
 
+For Pi 1.x compatibility, server entries also accept `type` as an alias for `transport`, `"http"` as an alias for `"streamable-http"`, `oauth` as an alias for `auth`, and `timeout` (in seconds) as an alias for `requestTimeoutMs`.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `transport` | `"stdio" \| "streamable-http" \| "sse"` | `"stdio"` | Transport protocol |
-| `command` | `string` | — | Executable to spawn (**required** for stdio) |
+| `transport` (or `type`) | `"stdio" \| "streamable-http" \| "http" \| "sse"` | `"stdio"` (`"streamable-http"` when `url` is set without `command`) | Transport protocol (`"http"` is normalized to `"streamable-http"`) |
+| `command` | `string` | — | Executable to spawn (**required** for `stdio`) |
 | `args` | `string[]` | `[]` | Arguments for the command |
-| `env` | `Record<string, string>` | — | Extra environment variables for the child process |
-| `url` | `string` | — | Server URL (**required** for streamable-http/sse) |
-| `headers` | `Record<string, string>` | — | Static headers sent with HTTP and SSE requests |
-| `auth` | `object` | — | OAuth configuration described below |
-| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` | `eager` = auto-start on session start, `lazy` = connect on request via `mcp_connect` or `/mcp:start` |
-| `requestTimeoutMs` | `number` | global setting | Per-server timeout override |
-| `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval for connection health monitoring |
+| `env` | `Record<string, string>` | — | Extra environment variables for the child process (literal values, no `${VAR}` interpolation) |
+| `url` | `string` | — | Server URL (**required** for `streamable-http` and `sse`) |
+| `headers` | `Record<string, string>` | — | Static headers sent with `streamable-http` and `sse` requests |
+| `auth` (or `oauth`) | `object` | — | OAuth 2.1 configuration described below and in [OAUTH.md](./OAUTH.md) (`streamable-http` / `sse` only) |
+| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` (`"eager"` for `pi.registerMcpServer()` unless `enabled: false`) | `eager` = auto-start on `session_start`, `lazy` = connect on request via `mcp_connect`, `/mcp:start`, or `/mcp:auth` |
+| `requestTimeoutMs` (or `timeout`) | `number` | global setting | Per-server timeout override in ms (`timeout` is specified in seconds and multiplied by `1000`) |
+| `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval in ms for proactive connection health monitoring |
 
 ### OAuth Config
 
+Configured under `auth` (or `oauth`). Token and client state are persisted per server in `<agent dir>/mcp-auth/<hash>.json` (`0700` directory, `0600` files on POSIX) with atomic writes and automatic backup of corrupt state files. See [OAUTH.md](./OAUTH.md) for architecture and troubleshooting details.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `type` | `"oauth"` | `"oauth"` | Authentication type |
-| `scope` | `string` | discovered | Requested scope when the server does not advertise one |
-| `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID |
+| `scope` | `string` | discovered | Requested scope when the server does not advertise one in `WWW-Authenticate` |
+| `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID (skips Dynamic Client Registration) |
 | `clientSecret` | `string` | — | Secret for a pre-registered confidential client |
-| `redirectUrl` | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback used by `/mcp:auth` |
+| `redirectUrl` (or `oauth.callbackUrl` / `oauth.callbackPort`) | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback (`localhost`, `127.0.0.1`, or `::1` with path `/callback` and an explicit non-zero port; `callbackPort` maps to `http://127.0.0.1:<port>/callback`). Scans forward from `19876` when omitted; binds the exact host and port when configured. |
 
 ## Commands
 
@@ -166,11 +182,18 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/mcp` | Show status summary of all configured servers |
 | `/mcp <name>` | Show detailed status and stderr log for a specific server |
 | `/mcp:start <name>` | Connect a server and wait for tool discovery |
-| `/mcp:stop <name>` | Cancel a pending connection or authorization, or stop a running server and deactivate its tools |
+| `/mcp:stop <name>` | Cancel a pending connection, startup prompt, or authorization, or stop a running server and deactivate its tools |
 | `/mcp:auth <name>` | Connect with stored OAuth credentials; request browser authorization only if needed |
 | `/mcp:auth <name> --reset` | Discard stored OAuth credentials and request fresh authorization |
 
-Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text. Repeated credential resets share one pending authorization; stop or shutdown cancels it. Lazy servers remain stopped until requested. An interactive Pi session is required when browser authorization is needed. Eager startup never opens a browser. Retry opens the browser again only when selected in the OAuth prompt.
+Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, discovered and active tool counts, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.
+
+### OAuth startup, headless/SSH, and concurrency behavior
+
+- **Interactive sessions required for browser auth**: Print and RPC sessions fail promptly when interactive authorization is required.
+- **Startup prompt for eager OAuth servers**: Silent startup and background reconnects never open a browser unprompted or trigger Dynamic Client Registration when no client credentials are stored. When an `eager` OAuth server needs interactive authorization at startup in an interactive Pi session, Pi presents a sequential `<name> needs authorization` prompt (`Authorize now` / `Not now`). Choosing `Authorize now` runs the interactive OAuth flow; choosing `Not now` leaves the server stopped, shows a `run /mcp:auth <name>` footer hint, and remembers the decline for the rest of the session.
+- **Headless and SSH support**: While authorization is pending, Pi displays the authorization URL and offers `Retry: open browser again`, `Paste redirect URL`, and `Cancel authentication`. On remote/SSH or headless machines, open the URL locally and either forward the callback port (`ssh -L <port>:127.0.0.1:<port>`) or paste the browser's final `http://127.0.0.1:<port>/callback?code=...&state=...` redirect URL into `Paste redirect URL`. Only `https:` (or loopback `http:`) authorization URLs are passed to the system browser opener.
+- **Coordinated connects and cross-process locks**: Concurrent connect requests join an in-flight attempt, while `--reset` supersedes a normal connect and shares one pending reset. Cross-process interactive flows are serialized per server via `<agent dir>/mcp-auth/<hash>.json.lock` with a 30s heartbeat and automatic reclamation of locks from dead local PIDs or stale heartbeats (>90s), while allowing silent token refreshes to persist rotated tokens.
 
 ### Connection readiness and active tools
 
@@ -199,20 +222,20 @@ Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and
          ▼                  ▼
    Global/Project    ┌──────────────┐
    mcp.json files    │ MCP Servers  │
-                     │ (stdio/http) │
+   + Extensions      │ (stdio/http) │
                      └──────────────┘
 ```
 
-1. **Config is loaded** from global and project files (project overrides global by server name)
-2. **Eager servers connect** at session start without opening browsers; lazy servers wait for `mcp_connect` or `/mcp:start`
-3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages)
+1. **Config is loaded** from global `<agent dir>/mcp.json`, trusted project `.pi/mcp.json` (checked via `ctx.isProjectTrusted()` on `session_start`), and extension-registered servers (`pi.getMcpServers()` / `mcp_servers_change`), with `mcp.json` taking precedence over extension-registered servers and project entries overriding global ones
+2. **Eager servers connect** at `session_start` (offering a sequential `Authorize now` / `Not now` prompt when an eager OAuth server needs authorization in an interactive session); lazy servers wait for `mcp_connect`, `/mcp:start`, or `/mcp:auth`
+3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages) before a server enters `ready`
 4. **JSON Schema → TypeBox** conversion registers tools with Pi-compatible parameter schemas
-5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix)
+5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix) and pass through text and `image` content blocks (`ImageContent`)
 6. **Tools activate/deactivate** automatically as servers connect/disconnect
 7. **AbortSignal** is wired through to `notifications/cancelled` for clean cancellation
-8. **Reconnection** uses a fixed delay schedule with configurable max retries
+8. **Reconnection & recovery** uses a fixed delay schedule with configurable max retries on initial failure, health check failure, or unexpected transport close (`client.onclose`)
 9. **`list_changed` notifications** trigger re-discovery, deactivating stale tools automatically
-10. **Session shutdown** cleanly stops all servers and deactivates all tools
+10. **Session shutdown** cancels pending auth/connection flows, stops the callback server, deactivates all tools, and cleanly stops all servers (with a `SIGKILL` safety net for `stdio` child processes)
 
 ## MCP Spec Compliance
 
@@ -222,15 +245,16 @@ Implements the **MCP 2025-03-26** specification for tool clients:
 |---|---|
 | Protocol version `2025-03-26` (+ `2024-11-05` fallback) | ✅ |
 | `stdio` transport | ✅ |
-| `streamable-http` transport | ✅ |
+| `streamable-http` transport (including `"http"` / URL-only shorthand) | ✅ |
 | `sse` transport (legacy backwards compat) | ✅ |
+| OAuth 2.1 authorization (PKCE S256, RFC 9728 Protected Resource Metadata, RFC 7591 DCR) | ✅ |
 | Cursor-based `tools/list` pagination | ✅ |
-| `tools/call` with parameters | ✅ |
+| `tools/call` with parameters & `image` content (`ImageContent`) passthrough | ✅ |
 | `roots/list` capability (workspace root) | ✅ |
 | `notifications/tools/list_changed` (live refresh) | ✅ |
 | `notifications/cancelled` (AbortSignal) | ✅ |
 | `notifications/message` (structured logging) | ✅ |
-| `isError: true` distinction (protocol vs tool errors) | ✅ |
+| `isError: true` distinction (protocol vs tool errors, non-text filtered on error) | ✅ |
 | Tool annotations (`readOnlyHint`, `destructiveHint`, etc.) | ✅ |
 | Resources bridge | ⏳ v2 |
 | Prompts bridge | ⏳ v2 |
@@ -255,10 +279,11 @@ npm run test:integration
 ### Testing
 
 The test suite includes:
-- **Config validation** — Zod schema, global/project merge, defaults, error cases
-- **Server lifecycle** — Connect, retry, shutdown, health check, race conditions
-- **Tool bridge** — JSON Schema → TypeBox conversion, name sanitization, activate/deactivate
-- **End-to-end integration** — Real mock MCP server over stdio with tool discovery and execution
+- **Config & Pi 1.x compatibility** — Zod schema, `$PI_CODING_AGENT_DIR` resolution, global/project merge, project trust boundary (`ctx.isProjectTrusted()`), Pi 1.x schema aliases (`type: "http"`, URL-only HTTP, `oauth`, `timeout`), and dynamic `pi.getMcpServers()` / `mcp_servers_change`
+- **Server lifecycle & coordination** — Connect, retry, unexpected close recovery, shutdown with PID `SIGKILL` safety net, health check, concurrent connect/reset coordination, and cancellation
+- **OAuth 2.1 & auth locks** — Challenge discovery, PKCE, Dynamic Client Registration, startup authorization prompts, headless/SSH redirect URL paste-back, URL scheme validation, cross-process lock heartbeat and stale lock reclamation
+- **Tool bridge & management tools** — JSON Schema → TypeBox conversion, name sanitization, image content passthrough, `isError` filtering, activate/deactivate, `mcp_status` / `mcp_connect`, and slash command completions
+- **End-to-end integration** — Real mock MCP and OAuth servers over stdio and HTTP with tool discovery and execution
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [
@@ -37,8 +37,8 @@
     "zod": "^3.25.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "devDependencies": {

package/src/callback-server.ts

@@ -149,7 +149,9 @@ async function closeCurrentServer(): Promise<void> {
  * scans forward from the default port if needed.
  */
 export function callbackServerConfigFromRedirectUrl(redirectUrl?: string): CallbackServerConfig {
-  if (!redirectUrl) {
+  // WHY: Only treat `undefined` (omitted) as default; an explicit empty string `""`
+  // must fall through to `new URL("")` and throw a validation error.
+  if (redirectUrl === undefined) {
     return {
       preferredPort: DEFAULT_PORT,
       host: DEFAULT_HOST,
@@ -236,7 +238,7 @@ export async function ensureCallbackServer(preferredPort: number = DEFAULT_PORT,
       });
 
       await new Promise<void>((resolve, reject) => {
-        candidateServer.once("error", (err: any) => {
+        candidateServer.once("error", (err: Error) => {
           reject(err);
         });
 

package/src/config.ts

@@ -14,99 +14,160 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
+import { callbackServerConfigFromRedirectUrl } from "./callback-server.js";
 import { McpError } from "./errors.js";
 
 // ─── Zod Schemas ──────────────────────────────────────────────────────────────
 
-const AuthConfigSchema = z.object({
-  /** Auth type. Currently only "oauth" is supported. Default: "oauth". */
-  type: z.enum(["oauth"]).default("oauth"),
-  /**
-   * Callback URL for the OAuth redirect.
-   * Default: auto-detected local callback server.
-   */
-  redirectUrl: z.string().optional(),
-  /**
-   * Optional scope to request during authorization.
-   */
-  scope: z.string().optional(),
-  /**
-   * Pre-registered client_id (skip dynamic client registration).
-   */
-  clientId: z.string().optional(),
-  /**
-   * Pre-registered client_secret.
-   */
-  clientSecret: z.string().optional(),
-});
-
-const ServerConfigSchema = z
-  .object({
-    /** Executable to spawn (e.g. "npx", "node", "uvx"). Required for stdio. */
-    command: z.string().optional(),
-    /** Arguments passed to command. */
-    args: z.array(z.string()).default([]),
-    /**
-     * Extra environment variables passed to the child process as literals.
-     * These merge with process.env; project env overrides parent env.
-     * No ${VAR} interpolation — set vars in your shell environment instead.
-     */
-    env: z.record(z.string()).optional(),
-    /** Transport protocol. Default: "stdio". */
-    transport: z.enum(["stdio", "streamable-http", "sse"]).default("stdio"),
-    /**
-     * URL for streamable-http or sse transports.
-     * Must be a valid URL (e.g. "https://my-mcp-server.example.com/mcp").
-     */
-    url: z.string().url().optional(),
-    /**
-     * Static HTTP headers to include with every request (streamable-http / sse only).
-     * Useful for API-key-based auth (e.g. { "Authorization": "Bearer <key>" }).
-     * For OAuth2, use the "auth" field instead.
-     */
-    headers: z.record(z.string()).optional(),
-    /**
-     * OAuth2 configuration for servers that require authorization.
-     * When set, the transport will use the SDK's OAuth flow (discovery,
-     * dynamic client registration, PKCE, token refresh).
-     * Only applies to streamable-http and sse transports.
-     */
-    auth: AuthConfigSchema.optional(),
-    /**
-     * "eager" — start at session_start.
-     * "lazy"  — start manually via /mcp:start command.
-     */
-    lifecycle: z.enum(["eager", "lazy"]).default("lazy"),
-    /** Per-request timeout in ms. Overrides global setting. Default: 30000. */
-    requestTimeoutMs: z.number().positive().optional(),
-    /**
-     * Opt-in heartbeat interval (ping) in ms.
-     * Only useful for long-lived connections where you want proactive liveness checks.
-     * Default: disabled.
-     */
-    healthCheckIntervalMs: z.number().positive().optional(),
-  })
-  .refine(
-    (cfg) => {
-      if (cfg.transport === "stdio") return cfg.command !== undefined;
-      return cfg.url !== undefined;
-    },
-    (cfg) => ({
-      message:
-        cfg.transport === "stdio"
-          ? `"command" is required for stdio transport`
-          : `"url" is required for ${cfg.transport} transport`,
+const AuthConfigSchema = z.preprocess(
+  (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
+    const obj = { ...(raw as Record<string, unknown>) };
+    if (obj.redirectUrl === undefined) {
+      if (typeof obj.callbackUrl === "string") {
+        obj.redirectUrl = obj.callbackUrl;
+      } else if (typeof obj.callbackPort === "number") {
+        obj.redirectUrl = `http://127.0.0.1:${obj.callbackPort}/callback`;
+      } else if (obj.callbackUrl !== undefined) {
+        obj.redirectUrl = obj.callbackUrl;
+      }
+    }
+    delete obj.callbackUrl;
+    delete obj.callbackPort;
+    return obj;
+  },
+  z
+    .object({
+      /** Auth type. Currently only "oauth" is supported. Default: "oauth". */
+      type: z.enum(["oauth"]).default("oauth"),
+      /**
+       * Callback URL for the OAuth redirect.
+       * Default: auto-detected local callback server.
+       */
+      redirectUrl: z.string().optional(),
+      /**
+       * Optional scope to request during authorization.
+       */
+      scope: z.string().optional(),
+      /**
+       * Pre-registered client_id (skip dynamic client registration).
+       */
+      clientId: z.string().optional(),
+      /**
+       * Pre-registered client_secret.
+       */
+      clientSecret: z.string().optional(),
+    })
+    .superRefine((auth, ctx) => {
+      if (auth.redirectUrl !== undefined) {
+        try {
+          callbackServerConfigFromRedirectUrl(auth.redirectUrl);
+        } catch (err) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["redirectUrl"],
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
     }),
-  );
+);
+
+export const ServerConfigSchema = z.preprocess(
+  (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
+    const obj = { ...(raw as Record<string, unknown>) };
+    const rawTransport = obj.transport ?? obj.type;
+    if (rawTransport === "http") {
+      obj.transport = "streamable-http";
+    } else if (obj.transport === undefined && rawTransport !== undefined) {
+      obj.transport = rawTransport;
+    } else if (obj.transport === undefined && obj.url !== undefined && obj.command === undefined) {
+      obj.transport = "streamable-http";
+    }
+    if (obj.auth === undefined && obj.oauth && typeof obj.oauth === "object" && !Array.isArray(obj.oauth)) {
+      obj.auth = obj.oauth;
+    }
+    if (obj.requestTimeoutMs === undefined && typeof obj.timeout === "number" && obj.timeout > 0) {
+      obj.requestTimeoutMs = obj.timeout * 1000;
+    }
+    return obj;
+  },
+  z
+    .object({
+      /** Executable to spawn (e.g. "npx", "node", "uvx"). Required for stdio. */
+      command: z.string().optional(),
+      /** Arguments passed to command. */
+      args: z.array(z.string()).default([]),
+      /**
+       * Extra environment variables passed to the child process as literals.
+       * These merge with process.env; project env overrides parent env.
+       * No ${VAR} interpolation — set vars in your shell environment instead.
+       */
+      env: z.record(z.string()).optional(),
+      /** Transport protocol. Default: "stdio" (or "streamable-http" when "url" is provided). */
+      transport: z.enum(["stdio", "streamable-http", "sse"]).default("stdio"),
+      /**
+       * URL for streamable-http or sse transports.
+       * Must be a valid URL (e.g. "https://my-mcp-server.example.com/mcp").
+       */
+      url: z.string().url().optional(),
+      /**
+       * Static HTTP headers to include with every request (streamable-http / sse only).
+       * Useful for API-key-based auth (e.g. { "Authorization": "Bearer <key>" }).
+       * For OAuth2, use the "auth" field instead.
+       */
+      headers: z.record(z.string()).optional(),
+      /**
+       * OAuth2 configuration for servers that require authorization.
+       * When set, the transport will use the SDK's OAuth flow (discovery,
+       * dynamic client registration, PKCE, token refresh).
+       * Only applies to streamable-http and sse transports.
+       */
+      auth: AuthConfigSchema.optional(),
+      /**
+       * "eager" — start at session_start.
+       * "lazy"  — start manually via /mcp:start command.
+       */
+      lifecycle: z.enum(["eager", "lazy"]).default("lazy"),
+      /** Per-request timeout in ms. Overrides global setting. Default: 30000. */
+      requestTimeoutMs: z.number().positive().optional(),
+      /**
+       * Opt-in heartbeat interval (ping) in ms.
+       * Only useful for long-lived connections where you want proactive liveness checks.
+       * Default: disabled.
+       */
+      healthCheckIntervalMs: z.number().positive().optional(),
+    })
+    .refine(
+      (cfg) => {
+        if (cfg.transport === "stdio") return cfg.command !== undefined;
+        return cfg.url !== undefined;
+      },
+      (cfg) => ({
+        message:
+          cfg.transport === "stdio"
+            ? `"command" is required for stdio transport`
+            : `"url" is required for ${cfg.transport} transport`,
+      }),
+    )
+    .refine(
+      (cfg) => !(cfg.transport === "stdio" && cfg.auth !== undefined),
+      {
+        message: "OAuth authentication is only supported for 'sse' and 'streamable-http' transports, not 'stdio'",
+        path: ["auth"],
+      },
+    ),
+);
 
 const SettingsSchema = z.object({
   /**
    * Prefix used in Pi tool names: <prefix>_<server>_<tool>.
-   * Must match [a-zA-Z0-9_]. Default: "mcp".
+   * Must match ^[a-zA-Z][a-zA-Z0-9_]*$. Default: "mcp".
    */
   toolPrefix: z
     .string()
-    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "toolPrefix must start with a letter and contain only alphanumeric characters and underscores")
     .default("mcp"),
   /** Default per-request timeout in ms for all servers. Default: 30000. */
   requestTimeoutMs: z.number().positive().default(30000),
@@ -127,7 +188,7 @@ const McpConfigSchema = z.object({
 const ProjectSettingsSchema = z.object({
   toolPrefix: z
     .string()
-    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "toolPrefix must start with a letter and contain only alphanumeric characters and underscores")
     .optional(),
   requestTimeoutMs: z.number().positive().optional(),
   maxRetries: z.number().int().min(0).max(10).optional(),
@@ -145,16 +206,117 @@ export type ServerConfig = z.output<typeof ServerConfigSchema>;
 export type Settings = z.output<typeof SettingsSchema>;
 export type McpConfig = z.output<typeof McpConfigSchema>;
 
+export interface LoadConfigOptions {
+  /**
+   * Whether to read project-level `<cwd>/.pi/mcp.json`.
+   * Set to `false` when the project is untrusted (`ctx.isProjectTrusted() === false`)
+   * or during bootstrap before session trust is resolved.
+   * Default: `true`.
+   */
+  includeProjectConfig?: boolean;
+}
+
 // ─── Loader ───────────────────────────────────────────────────────────────────
 
-async function readJsonFile(path: string): Promise<unknown | null> {
+/**
+ * Strip `//` line comments and `/* ... *\/` block comments outside of double-quoted
+ * JSON strings in a single character-by-character pass.
+ *
+ * Preserves `\n` and `\r` characters so line numbers in `JSON.parse` error messages
+ * remain accurate. Unterminated `/*` block comments are left intact so `JSON.parse`
+ * fails with a syntax error rather than silently truncating the document.
+ */
+export function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i]!;
+
+    if (inString) {
+      if (ch === "\\") {
+        out += ch;
+        if (i + 1 < text.length) {
+          out += text[i + 1]!;
+          i += 2;
+        } else {
+          i += 1;
+        }
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "/" && text[i + 1] === "/") {
+      i += 2;
+      while (i < text.length && text[i] !== "\n") {
+        if (text[i] === "\r" && text[i + 1] === "\n") break;
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === "/" && text[i + 1] === "*") {
+      const closeIdx = text.indexOf("*/", i + 2);
+      if (closeIdx === -1) {
+        // WHY: Leave unterminated block comments intact so JSON.parse fails with a
+        // SyntaxError rather than silently truncating the rest of the file.
+        out += text.slice(i);
+        break;
+      }
+      for (let j = i; j < closeIdx + 2; j += 1) {
+        const commentCh = text[j]!;
+        out += commentCh === "\n" || commentCh === "\r" ? commentCh : " ";
+      }
+      i = closeIdx + 2;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+}
+
+async function readJsonFile(path: string): Promise<unknown> {
+  let text: string;
   try {
-    const text = await readFile(path, "utf8");
-    return JSON.parse(text) as unknown;
+    text = await readFile(path, "utf-8");
   } catch (err) {
-    // ENOENT → file doesn't exist, silently skip
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new McpError(
+      `Failed to read mcp.json at ${path}: ${detail}`,
+      "<config>",
+      "config",
+      err,
+    );
+  }
+
+  try {
+    return JSON.parse(stripJsonComments(text));
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new McpError(
+      `Invalid JSON in mcp.json at ${path}: ${detail}`,
+      "<config>",
+      "config",
+      err,
+    );
   }
 }
 
@@ -181,6 +343,36 @@ function parseWith<S extends z.ZodTypeAny>(
   return result.data;
 }
 
+/**
+ * Parse and normalize a server configuration registered via `pi.registerMcpServer()`.
+ * Extension-registered servers default to `lifecycle: "eager"` (unless `enabled: false`
+ * or `lifecycle` is explicitly specified) so they connect on `session_start` / `mcp_servers_change`.
+ */
+export function parseRegisteredServerConfig(
+  name: string,
+  raw: unknown,
+  sourcePath = "<extension>",
+): ServerConfig {
+  const rawObj = raw && typeof raw === "object" && !Array.isArray(raw)
+    ? (raw as Record<string, unknown>)
+    : undefined;
+  const withLifecycle = rawObj && rawObj.lifecycle === undefined
+    ? { ...rawObj, lifecycle: rawObj.enabled === false ? "lazy" : "eager" }
+    : raw;
+  const result = ServerConfigSchema.safeParse(withLifecycle);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  mcpServers.${name}${i.path.length ? `.${i.path.join(".")}` : ""}: ${i.message}`)
+      .join("\n");
+    throw new McpError(
+      `Invalid MCP server "${name}" from ${sourcePath}:\n${issues}`,
+      name,
+      "config",
+    );
+  }
+  return result.data;
+}
+
 function mergeConfigs(
   globalCfg: McpConfig,
   projectCfg: ProjectConfig,
@@ -199,7 +391,7 @@ function mergeConfigs(
 
 /**
  * Pi's agent directory, resolved the way Pi resolves it (`getAgentDir()` in
- * @mariozechner/pi-coding-agent): $PI_CODING_AGENT_DIR when set (tilde expanded), else
+ * @earendil-works/pi-coding-agent): $PI_CODING_AGENT_DIR when set (tilde expanded), else
  * ~/.pi/agent. Pi profiles and alternative agent dirs only work through that variable.
  */
 export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
@@ -214,27 +406,32 @@ export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
 
 /**
  * Load and merge global (<agent dir>/mcp.json) and project (<cwd>/.pi/mcp.json) configs.
- * Project config takes precedence over global config.
+ * Project config takes precedence over global config when `options.includeProjectConfig !== false`.
  * Returns a fully validated, merged config.
  */
-export async function loadConfig(cwd: string, globalPath = join(agentDir(), "mcp.json")): Promise<McpConfig> {
+export async function loadConfig(
+  cwd: string,
+  globalPath = join(agentDir(), "mcp.json"),
+  options?: LoadConfigOptions,
+): Promise<McpConfig> {
+  const includeProjectConfig = options?.includeProjectConfig !== false;
   const projectPath = join(cwd, ".pi", "mcp.json");
 
   const [globalRaw, projectRaw] = await Promise.all([
     readJsonFile(globalPath),
-    readJsonFile(projectPath),
+    includeProjectConfig ? readJsonFile(projectPath) : Promise.resolve(undefined),
   ]);
 
   // If neither file exists, return an empty valid config
-  if (globalRaw === null && projectRaw === null) {
+  if (globalRaw === undefined && projectRaw === undefined) {
     return McpConfigSchema.parse({});
   }
 
-  const globalCfg = globalRaw !== null
+  const globalCfg = globalRaw !== undefined
     ? parseConfig(globalRaw, globalPath)
     : McpConfigSchema.parse({});
 
-  if (projectRaw === null) return globalCfg;
+  if (projectRaw === undefined) return globalCfg;
 
   const projectCfg = parseWith(ProjectConfigSchema, projectRaw, projectPath);
   return mergeConfigs(globalCfg, projectCfg);

package/src/index.ts

@@ -7,8 +7,14 @@
  * Wires together: config → server manager → tool bridge → Pi API.
  */
 
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, ExtensionUIContext } from "@mariozechner/pi-coding-agent";
-import { loadConfig, type McpConfig } from "./config.js";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+  ExtensionUIContext,
+  RegisteredMcpServer,
+} from "@earendil-works/pi-coding-agent";
+import { loadConfig, parseRegisteredServerConfig, type McpConfig, type ServerConfig } from "./config.js";
 import { ServerManager } from "./server-manager.js";
 import { AuthLockError, AuthRequiredError } from "./oauth-provider.js";
 import * as Type from "typebox";
@@ -281,26 +287,73 @@ export function serverNameCompletions(
   return completions.length > 0 ? completions : null;
 }
 
+function collectRegisteredServers(
+  entries: readonly RegisteredMcpServer[],
+  fileServers: Record<string, ServerConfig>,
+  onError?: (err: unknown) => void,
+): Record<string, ServerConfig> {
+  const registered: Record<string, ServerConfig> = {};
+  for (const entry of entries) {
+    // Servers configured in mcp.json take precedence over extension-registered servers.
+    if (Object.prototype.hasOwnProperty.call(fileServers, entry.name)) {
+      continue;
+    }
+    try {
+      registered[entry.name] = parseRegisteredServerConfig(
+        entry.name,
+        entry.config,
+        entry.extensionPath || "<extension>",
+      );
+    } catch (err) {
+      onError?.(err);
+    }
+  }
+  return registered;
+}
+
+function mergeWithRegisteredServers(
+  fileConfig: McpConfig,
+  registeredServers: Record<string, ServerConfig>,
+): McpConfig {
+  return {
+    settings: fileConfig.settings,
+    mcpServers: {
+      ...registeredServers,
+      ...fileConfig.mcpServers,
+    },
+  };
+}
+
 export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string; globalConfigPath?: string; authStorageDir?: string; browserOpen?: (url: string) => void | Promise<void> } = {}): Promise<void> {
   // ── 1. Load and validate config ──────────────────────────────────────────
-  // cwd is available on the ExtensionContext passed to event handlers.
-  // We load config lazily on session_start to get the correct per-session cwd.
-  // For the initial load we use process.cwd() as a bootstrap path to detect
-  // whether any config exists at all.
-  let config: McpConfig;
+  // cwd and project trust are available on the ExtensionContext passed to event handlers.
+  // At bootstrap (before session_start) we load ONLY the global config so untrusted
+  // <cwd>/.pi/mcp.json files are never read before ctx.isProjectTrusted() is checked.
+  let fileConfig: McpConfig = {
+    settings: { toolPrefix: "mcp", requestTimeoutMs: 30000, maxRetries: 5 },
+    mcpServers: {},
+  };
   try {
-    config = await loadConfig(paths.bootstrapCwd ?? process.cwd(), paths.globalConfigPath);
+    fileConfig = await loadConfig(paths.bootstrapCwd ?? process.cwd(), paths.globalConfigPath, {
+      includeProjectConfig: false,
+    });
   } catch (err) {
     // Can't notify yet (no ctx), so log to stderr. The session_start handler
     // will re-try with the real cwd and surface errors properly.
     console.error(`[pi-mcp] Config error: ${err instanceof McpError ? err.message : String(err)}`);
-    return;
   }
 
-  if (Object.keys(config.mcpServers).length === 0) {
-    // No servers configured — silently exit. Users can create mcp.json later.
-    return;
-  }
+  const getRegisteredEntries = (): RegisteredMcpServer[] =>
+    typeof (pi as { getMcpServers?: () => RegisteredMcpServer[] }).getMcpServers === "function"
+      ? pi.getMcpServers()
+      : [];
+
+  let extensionServers = collectRegisteredServers(
+    getRegisteredEntries(),
+    fileConfig.mcpServers,
+    (err) => console.error(`[pi-mcp] Config error: ${err instanceof McpError ? err.message : String(err)}`),
+  );
+  let config: McpConfig = mergeWithRegisteredServers(fileConfig, extensionServers);
 
   // ── 2. Initialize bridge components ──────────────────────────────────────
   const manager = new ServerManager(config, undefined, paths.authStorageDir);
@@ -391,6 +444,42 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
     })();
   }
 
+  async function startEagerServers(
+    serversToStart: Array<[string, ServerConfig]>,
+    ctx: ExtensionContext,
+  ): Promise<void> {
+    const authRequiredServers = new Set<string>();
+
+    // Start all eager servers concurrently
+    await Promise.allSettled(
+      serversToStart.map(async ([name, cfg]) => {
+        try {
+          await manager.startServer(name, ctx.cwd);
+        } catch (err) {
+          if (err instanceof AuthRequiredError && cfg.auth && ctx.hasUI) {
+            authRequiredServers.add(name);
+            return;
+          }
+          const msg = formatErrorMessage(err);
+          ctx.ui.notify(`pi-mcp: Failed to start ${name} — ${msg}`, "error");
+        }
+      }),
+    );
+
+    for (const [name] of serversToStart) {
+      if (!authRequiredServers.has(name)) continue;
+      if (declinedStartupAuth.has(name)) {
+        ctx.ui.setStatus?.("pi-mcp", `run /mcp:auth ${name}`);
+        continue;
+      }
+      enqueueStartupAuthPrompt(name, ctx);
+    }
+
+    for (let i = 0; i < 4 * authRequiredServers.size; i++) {
+      await Promise.resolve();
+    }
+  }
+
   manager.setToolRefreshCallback(async (serverName, client) => {
     await bridge.refreshTools(serverName, client, () => {
       const server = manager.getServer(serverName);
@@ -401,17 +490,33 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
 
   // ── 3. Session lifecycle ──────────────────────────────────────────────────
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
-    // Reload config with the real session cwd (project config may differ)
-    let sessionConfig = config;
+    // Only load project-level <cwd>/.pi/mcp.json when the project is trusted.
+    const includeProjectConfig =
+      typeof (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted === "function"
+        ? (ctx as { isProjectTrusted: () => boolean }).isProjectTrusted()
+        : true;
+
+    let nextFileConfig = fileConfig;
     try {
-      sessionConfig = await loadConfig(ctx.cwd, paths.globalConfigPath);
+      nextFileConfig = await loadConfig(ctx.cwd, paths.globalConfigPath, { includeProjectConfig });
     } catch (err) {
       const msg = formatErrorMessage(err);
       ctx.ui.notify(`pi-mcp: Config error — ${msg}`, "error");
       return;
     }
 
-    // If config changed (different cwd with project-level overrides),
+    fileConfig = nextFileConfig;
+    extensionServers = collectRegisteredServers(
+      getRegisteredEntries(),
+      fileConfig.mcpServers,
+      (err) => {
+        const msg = formatErrorMessage(err);
+        ctx.ui.notify(`pi-mcp: Config error — ${msg}`, "error");
+      },
+    );
+    const sessionConfig = mergeWithRegisteredServers(fileConfig, extensionServers);
+
+    // If config changed (different cwd with project-level overrides or registered servers),
     // shut down old servers and rebuild the manager's server list
     if (JSON.stringify(sessionConfig) !== JSON.stringify(config)) {
       declinedStartupAuth.clear();
@@ -426,6 +531,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       // Shut down all running servers
       await manager.shutdownAll();
       // Rebuild server entries from new config
+      bridge.updateSettings(sessionConfig.settings);
       manager.rebuildServers(sessionConfig);
       config = sessionConfig;
     }
@@ -434,35 +540,56 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       ([, cfg]) => cfg.lifecycle === "eager",
     );
 
-    const authRequiredServers = new Set<string>();
+    await startEagerServers(eagerServers, ctx);
+  });
 
-    // Start all eager servers concurrently
-    await Promise.allSettled(
-      eagerServers.map(async ([name, cfg]) => {
-        try {
-          await manager.startServer(name, ctx.cwd);
-        } catch (err) {
-          if (err instanceof AuthRequiredError && cfg.auth && ctx.hasUI) {
-            authRequiredServers.add(name);
-            return;
-          }
-          const msg = formatErrorMessage(err);
-          ctx.ui.notify(`pi-mcp: Failed to start ${name} — ${msg}`, "error");
-        }
-      }),
+  // Connect or disconnect MCP servers registered dynamically via pi.registerMcpServer().
+  pi.on("mcp_servers_change", async (event, ctx: ExtensionContext) => {
+    const entries = Array.isArray((event as { servers?: unknown })?.servers)
+      ? ((event as { servers: RegisteredMcpServer[] }).servers)
+      : getRegisteredEntries();
+
+    const nextExtensionServers = collectRegisteredServers(
+      entries,
+      fileConfig.mcpServers,
+      (err) => {
+        const msg = formatErrorMessage(err);
+        ctx.ui.notify(`pi-mcp: Config error — ${msg}`, "error");
+      },
     );
 
-    for (const [name] of eagerServers) {
-      if (!authRequiredServers.has(name)) continue;
-      if (declinedStartupAuth.has(name)) {
-        ctx.ui.setStatus?.("pi-mcp", `run /mcp:auth ${name}`);
-        continue;
+    const removedOrChanged: string[] = [];
+    for (const [name, prevCfg] of Object.entries(extensionServers)) {
+      const nextCfg = nextExtensionServers[name];
+      if (!nextCfg || JSON.stringify(prevCfg) !== JSON.stringify(nextCfg)) {
+        removedOrChanged.push(name);
       }
-      enqueueStartupAuthPrompt(name, ctx);
     }
 
-    for (let i = 0; i < 4 * authRequiredServers.size; i++) {
-      await Promise.resolve();
+    for (const name of removedOrChanged) {
+      declinedStartupAuth.delete(name);
+      startupPromptControllers.get(name)?.abort();
+      startupPromptControllers.delete(name);
+      connectAttempts.get(name)?.controller.abort();
+      bridge.removeServer(name);
+      await manager.removeServer(name);
+    }
+
+    const addedEager: Array<[string, ServerConfig]> = [];
+    for (const [name, nextCfg] of Object.entries(nextExtensionServers)) {
+      if (!manager.getServer(name)) {
+        manager.setServer(name, nextCfg);
+        if (nextCfg.lifecycle === "eager") {
+          addedEager.push([name, nextCfg]);
+        }
+      }
+    }
+
+    extensionServers = nextExtensionServers;
+    config = mergeWithRegisteredServers(fileConfig, extensionServers);
+
+    if (addedEager.length > 0) {
+      await startEagerServers(addedEager, ctx);
     }
   });
 

package/src/server-manager.ts

@@ -256,6 +256,30 @@ export class ServerManager {
     );
   }
 
+  /** Add or replace a stopped server entry in the manager. */
+  setServer(name: string, serverConfig: ServerConfig): void {
+    this.servers.set(name, {
+      name,
+      config: serverConfig,
+      state: "stopped",
+      client: null,
+      childPid: null,
+      retryCount: 0,
+      lastError: null,
+      stderrLog: [],
+      healthCheckTimer: null,
+      retryTimer: null,
+    });
+  }
+
+  /** Shut down and remove a server entry from the manager. */
+  async removeServer(name: string): Promise<void> {
+    const server = this.servers.get(name);
+    if (!server) return;
+    await this._shutdown(server);
+    this.servers.delete(name);
+  }
+
   /**
    * Rebuild the server map from a new config.
    * Must only be called after shutdownAll() — old servers are discarded.
@@ -266,18 +290,7 @@ export class ServerManager {
     this.settings = config.settings;
     this.servers.clear();
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
-      this.servers.set(name, {
-        name,
-        config: serverConfig,
-        state: "stopped",
-        client: null,
-        childPid: null,
-        retryCount: 0,
-        lastError: null,
-        stderrLog: [],
-        healthCheckTimer: null,
-        retryTimer: null,
-      });
+      this.setServer(name, serverConfig);
     }
   }
 

package/src/tool-bridge.ts

@@ -16,7 +16,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import * as Type from "typebox";
 import type { TSchema } from "typebox";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { McpError } from "./errors.js";
 import type { Settings } from "./config.js";
 
@@ -313,7 +313,7 @@ export async function listAllTools(
  * Tools are registered once and activated/deactivated as servers connect/disconnect.
  */
 export class ToolBridge {
-  private readonly settings: Settings;
+  private settings: Settings;
   private readonly pi: PiExtensionAPI;
   /** Tracks which Pi tool names belong to which MCP server. */
   private readonly serverToolNames = new Map<string, Set<string>>();
@@ -323,6 +323,11 @@ export class ToolBridge {
     this.pi = pi;
   }
 
+  /** Update bridge settings when session config is reloaded on session_start. */
+  updateSettings(settings: Settings): void {
+    this.settings = settings;
+  }
+
   /**
    * Refresh tools for a server — called on initial connect and on list_changed.
    * Always re-registers tools with the current client reference so that