pi-code 1.0.26 → 1.0.28

package/extensions/internal/mcp-oauth.ts

@@ -28,6 +28,17 @@ interface StoredAuth {
   redirectPort?: number
 }
 
+/** Claude's per-server `oauth` config object: a pre-registered client (secret via
+ * MCP_CLIENT_SECRET), a fixed callback port for pre-registered redirect URIs, and
+ * pinned scopes. authServerMetadataUrl is accepted but unsupported (the MCP SDK
+ * offers no discovery override); the connect path warns when it is set. */
+export interface OAuthServerConfig {
+  clientId?: string
+  callbackPort?: number
+  scopes?: string
+  authServerMetadataUrl?: string
+}
+
 /** A server name is config-controlled text; the digest keeps hostile names inside
  * the store directory and distinct names from colliding after sanitization. */
 function storeFileFor(serverName: string): string {
@@ -55,9 +66,10 @@ export class FileOAuthProvider implements OAuthClientProvider {
   // page cannot inject an authorization code into this login (RFC 8252 8.9).
   private readonly loginState = crypto.randomBytes(16).toString('hex')
 
-  constructor(serverName: string, onRedirect: (authorizationUrl: URL) => void) {
+  constructor(serverName: string, onRedirect: (authorizationUrl: URL) => void, oauth?: OAuthServerConfig) {
     this.storePath = storeFileFor(serverName)
     this.onRedirect = onRedirect
+    this.oauth = oauth
     try {
       this.data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'))
     } catch {
@@ -65,14 +77,22 @@ export class FileOAuthProvider implements OAuthClientProvider {
     }
   }
 
+  private readonly oauth?: OAuthServerConfig
+
+  /** The client secret for a pre-configured client, from Claude's MCP_CLIENT_SECRET. */
+  private clientSecret(): string | undefined {
+    return this.oauth?.clientId ? process.env.MCP_CLIENT_SECRET : undefined
+  }
+
   private persist(): void {
     fs.mkdirSync(path.dirname(this.storePath), { recursive: true })
     fs.writeFileSync(this.storePath, JSON.stringify(this.data), { mode: 0o600 })
   }
 
-  /** The port a prior login registered, so a re-login can bind the same one. */
+  /** The configured callbackPort (Claude: for pre-registered redirect URIs), else
+   * the port a prior login registered, so a re-login can bind the same one. */
   savedRedirectPort(): number | undefined {
-    return this.data.redirectPort
+    return this.oauth?.callbackPort ?? this.data.redirectPort
   }
 
   /** Record the loopback port the callback server actually bound; the redirect
@@ -96,11 +116,19 @@ export class FileOAuthProvider implements OAuthClientProvider {
       grant_types: ['authorization_code', 'refresh_token'],
       response_types: ['code'],
       // A local CLI is a public client; PKCE carries the proof instead of a secret.
-      token_endpoint_auth_method: 'none',
+      // A pre-configured client with an MCP_CLIENT_SECRET authenticates with it.
+      token_endpoint_auth_method: this.clientSecret() ? 'client_secret_post' : 'none',
+      // Claude: oauth.scopes pins the scopes requested during authorization.
+      ...(this.oauth?.scopes ? { scope: this.oauth.scopes } : {}),
     }
   }
 
   clientInformation(): OAuthClientInformationMixed | undefined {
+    // A pre-configured clientId replaces dynamic registration entirely.
+    if (this.oauth?.clientId) {
+      const secret = this.clientSecret()
+      return { client_id: this.oauth.clientId, ...(secret ? { client_secret: secret } : {}) }
+    }
     return this.data.client
   }
 

package/extensions/mcp/config.ts

@@ -7,6 +7,7 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { claudeConfigDir } from '../internal/config-dir.js'
+import type { OAuthServerConfig } from '../internal/mcp-oauth.js'
 import type { InstalledPlugin } from '../internal/plugins.js'
 import { findNearestFile } from '../internal/project-root.js'
 
@@ -20,6 +21,10 @@ export interface StdioServerConfig {
   timeout?: number
   /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
   aliasPrefix?: string
+  /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
+  pluginRoot?: string
+  /** Loaded from the project scope, whose helpers run credential-stripped. */
+  projectScope?: boolean
 }
 
 export interface HttpServerConfig {
@@ -28,6 +33,8 @@ export interface HttpServerConfig {
   headers?: Record<string, string>
   bearerToken?: string
   bearerTokenEnv?: string
+  /** Claude's oauth object: pre-registered client, fixed callback port, pinned scopes. */
+  oauth?: OAuthServerConfig
   /** A command whose JSON stdout is merged into the connect headers, for auth
    * schemes other than OAuth/static tokens (Claude's headersHelper). */
   headersHelper?: string
@@ -35,6 +42,10 @@ export interface HttpServerConfig {
   timeout?: number
   /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
   aliasPrefix?: string
+  /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
+  pluginRoot?: string
+  /** Loaded from the project scope, whose helpers run credential-stripped. */
+  projectScope?: boolean
 }
 
 export type ServerConfig = StdioServerConfig | HttpServerConfig
@@ -200,7 +211,7 @@ export function loadPluginServers(plugins: InstalledPlugin[], projectDir?: strin
   for (const plugin of plugins) {
     for (const [name, config] of Object.entries(rawPluginServerEntries(plugin))) {
       const substituted = substitutedPluginServer(plugin, name, config, projectDir)
-      if (substituted) servers[name] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__` }
+      if (substituted) servers[name] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, pluginRoot: plugin.root }
     }
   }
   return servers

package/extensions/mcp/index.ts

@@ -20,8 +20,9 @@
  * environment plus its own `env` block, not the whole process environment.
  *
  * Servers advertising the `prompts` capability get their prompts registered as Claude's
- * /mcp__<server>__<prompt> slash commands (names normalized dashes/spaces to underscores,
- * args space-separated and mapped positionally); the prompt result drives a turn via
+ * /mcp__<server>__<prompt> slash commands (server-name characters outside A-Za-z0-9_-
+ * fold to underscores, args split on whitespace and mapped positionally, one token
+ * per declared argument); the prompt result drives a turn via
  * sendUserMessage, exactly how custom slash commands do. Servers advertising `resources`
  * make the global list_mcp_resources / read_mcp_resource tools available, mirroring
  * Claude's automatic resource tools. Resource and prompt output rides the same
@@ -47,7 +48,7 @@ import { disabledServerNames, loadConfigFrom, loadPluginServers, loadUserScope,
 import { collectServerResourceEntries, listAllPrompts, listAllTools, type McpToolInfo, resourceServerFilter } from './listing.js'
 import { formatPromptCommandName, formatToolName, type McpContentBlock, type McpPromptInfo, mapContent, mapPromptArguments, normalizeSchema, promptMessageContent } from './mapping.js'
 import { applyServerPolicy, loadManagedMcpServers, type McpPolicy, mcpAllowDeny, projectServerPolicy, splitByPolicy } from './policy.js'
-import { type AuthUi, callRequestOptions, callTimeoutMs, connect, connectTimeoutMs, type ServerCallTuning, serverCallTuning, withTimeout } from './transport.js'
+import { type AuthUi, callRequestOptions, callTimeoutMs, connect, connectTimeoutMs, connectWithRetries, isUnauthorized, type ServerCallTuning, type SessionDirs, serverCallTuning, withTimeout } from './transport.js'
 
 export { managedSettingsPath, setManagedSettingsPath } from '../internal/managed-settings.js'
 // Re-exports for consumers: the module split keeps the extension's public surface
@@ -87,16 +88,28 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   // Config per server name, kept for call-time timeout tuning: the idle tier follows
   // the transport kind, and a declared per-server timeout governs the wall budget.
   const serverConfigs = new Map<string, ServerConfig>()
+  // The session's directories, set at session_start before any connect: the launch
+  // directory answers roots/list, the project root feeds CLAUDE_PROJECT_DIR.
+  let sessionDirs: SessionDirs | undefined
+  // Shutdown closes clients while they are still in the map; the onclose handlers
+  // must not schedule reconnects for that deliberate teardown.
+  let shuttingDown = false
   const callTuning = (name: string): ServerCallTuning => {
     const config = serverConfigs.get(name)
     return config ? serverCallTuning(config) : {}
   }
   // Let other extensions (hooks' mcp_tool type) call a connected server's tool.
+  // The same 401/403 reconnect-and-retry-once as registered tools, when the
+  // server's config is known; a name with no stored config calls through once.
   setMcpToolCaller(async (server, tool, input) => {
-    const client = clients.get(server)
-    if (!client) throw new Error(`MCP server "${server}" is not connected`)
-    const tuning = callTuning(server)
-    const result = await client.callTool({ name: tool, arguments: input }, undefined, callRequestOptions(tuning.serverTimeoutMs ?? callTimeoutMs(), tuning))
+    const config = serverConfigs.get(server)
+    const result = config
+      ? await callToolWithAuthRetry(server, config, { name: tool, arguments: input }, `${server}: ${tool}`)
+      : await (async () => {
+          const client = clients.get(server)
+          if (!client) throw new Error(`MCP server "${server}" is not connected`)
+          return await client.callTool({ name: tool, arguments: input }, undefined, callRequestOptions(callTimeoutMs()))
+        })()
     const text = mapContent(result.content as McpContentBlock[], result.structuredContent)
       .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
       .map((part) => part.text)
@@ -138,17 +151,13 @@ export default async function mcpExtension(pi: ExtensionAPI) {
           // present at registration: pi has no tool unregister, so after a server drops
           // and a later session_start reconnects it, registerTools skips re-registration
           // and this closure would otherwise keep calling the old, closed client.
-          const current = clients.get(name)
-          if (!current) throw new Error(`MCP server "${name}" is not connected`)
           // The per-server timeout (Claude's, 1s floor) or MCP_TOOL_TIMEOUT is the
           // wall-clock ceiling; callRequestOptions layers the idle timeout under it, which
-          // the SDK enforces (resetting on progress). Pass the options to the SDK too: its
-          // own default request timeout is 60s and would otherwise reject first. The outer
-          // race uses the wall budget, never the idle window, so a progressing call is not
-          // cut off at the idle timeout.
-          const tuning = serverCallTuning(config)
-          const wall = tuning.serverTimeoutMs ?? callTimeoutMs()
-          const result = await withTimeout(current.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, callRequestOptions(wall, tuning)), wall, toolName)
+          // the SDK enforces (resetting on progress). The outer race uses the wall
+          // budget, never the idle window, so a progressing call is not cut off at the
+          // idle timeout. A 401/403 reconnects once (fresh helper headers or refreshed
+          // OAuth tokens) and retries once.
+          const result = await callToolWithAuthRetry(name, config, { name: tool.name, arguments: params as Record<string, unknown> }, toolName)
           const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
           const details: { error?: string } = {}
           if (result.isError) {
@@ -163,6 +172,53 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     return count
   }
 
+  /** Claude's mid-session reconnect for a dropped remote server: five attempts with
+   * a delay doubling from one second. connectServers redoes the full bring-up
+   * (tools, prompts, subscriptions, a fresh onclose) and its duplicate guard skips
+   * out if another path already reconnected the name. Runs without authUi: a server
+   * that now needs a login ends failed, and after the fifth failure the last
+   * attempt's failed status stands, with a session restart as the manual retry. */
+  async function reconnectWithBackoff(name: string, config: ServerConfig): Promise<void> {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt))
+      if (shuttingDown || clients.has(name)) return
+      await connectServers({ [name]: config }, undefined, true)
+      if (clients.has(name)) return
+    }
+  }
+
+  /** Claude's 401/403 tool-call recovery: drop the client and reconnect once, so the
+   * headersHelper re-runs (fresh credential) or the OAuth tokens refresh, then the
+   * caller retries the call once. The map delete precedes the close so the onclose
+   * guard does not also schedule a backoff reconnect. */
+  async function reconnectForAuth(name: string, config: ServerConfig): Promise<void> {
+    const old = clients.get(name)
+    if (old) {
+      clients.delete(name)
+      await withTimeout(old.close(), 3000, 'close').catch(() => {})
+    }
+    await connectServers({ [name]: config }, undefined, true)
+  }
+
+  /** A tool call with the auth retry: on a 401/403 rejection, reconnect once and
+   * retry once; a second auth failure surfaces to the caller. */
+  async function callToolWithAuthRetry(name: string, config: ServerConfig, args: { name: string; arguments: Record<string, unknown> }, label: string): Promise<Awaited<ReturnType<Client['callTool']>>> {
+    const tuning = serverCallTuning(config)
+    const wall = tuning.serverTimeoutMs ?? callTimeoutMs()
+    const callOnce = async () => {
+      const current = clients.get(name)
+      if (!current) throw new Error(`MCP server "${name}" is not connected`)
+      return await withTimeout(current.callTool(args, undefined, callRequestOptions(wall, tuning)), wall, label)
+    }
+    try {
+      return await callOnce()
+    } catch (error) {
+      if (!isUnauthorized(error)) throw error
+      await reconnectForAuth(name, config)
+      return await callOnce()
+    }
+  }
+
   // Prompt command name -> the server and prompt that own it, so a refresh re-listing
   // the same prompt is told apart both from a cross-server collision and from a second
   // prompt on the same server whose name normalizes to the one already taken (e.g.
@@ -336,7 +392,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     }
   }
 
-  async function connectServers(servers: Record<string, ServerConfig>, authUi?: AuthUi): Promise<void> {
+  async function connectServers(servers: Record<string, ServerConfig>, authUi?: AuthUi, noRetry = false): Promise<void> {
     const pending: [string, ServerConfig][] = []
     for (const [name, config] of Object.entries(servers)) {
       // A later scope must not take the name of a server that already connected: it
@@ -356,7 +412,9 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       pending.map(async ([name, config]) => {
         warnOnTypelessUrl(name, config)
         try {
-          const client = await connect(name, config, authUi)
+          // First connections retry transient failures (Claude: up to three times for
+          // HTTP/SSE); the backoff reconnect below carries its own schedule instead.
+          const client = noRetry ? await connect(name, config, authUi, sessionDirs) : await connectWithRetries(name, config, authUi, sessionDirs)
           clients.set(name, client)
           const tools = await withTimeout(listAllTools(client), connectTimeoutMs(), `list tools ${name}`)
           registerTools(name, config, tools)
@@ -378,6 +436,11 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             if (clients.get(name) !== client) return
             clients.delete(name)
             status.set(name, { state: 'disconnected', tools: 0 })
+            // Claude reconnects a dropped remote server with exponential backoff;
+            // stdio servers are local processes and are not reconnected. Shutdown
+            // closes clients while they are still in the map, so the flag guards
+            // against scheduling a reconnect for a deliberate teardown.
+            if (!shuttingDown && !serverCallTuning(config).stdio) void reconnectWithBackoff(name, config)
           }
         } catch (error) {
           status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
@@ -448,7 +511,10 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // The stored project decision, read without prompting: consent recorded inside
     // the project only counts once the project itself has been approved.
     const projectPolicy = projectServerPolicy(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
-    const { consented: consentedRaw, gated } = splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), policy), projectPolicy)
+    // Tag the scope on each project server: a repository-supplied headersHelper runs
+    // with credential variables stripped, unlike a user-scope one.
+    const projectServers = Object.fromEntries(Object.entries(loadConfigFrom(projectConfigPaths(ctx.cwd))).map(([name, config]) => [name, { ...config, projectScope: true }]))
+    const { consented: consentedRaw, gated } = splitByPolicy(applyServerPolicy(projectServers, policy), projectPolicy)
     // Claude's scope precedence is local over project: a name the local scope defines
     // stays with the local (user-side) definition, so the project's entry is dropped
     // here rather than allowed to shadow it.
@@ -480,6 +546,12 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // withdrawn tool keeps its registration and surfaces the server's own error), which
     // is why serverToolCount reads from `registered` to recover the true count here.
     status.clear()
+    // A same-process session switch (/new, /resume) shut the last session down;
+    // this one may reconnect again.
+    shuttingDown = false
+    // Claude answers roots/list with the session's launch directory and exports the
+    // project root as CLAUDE_PROJECT_DIR to stdio servers; both derive from ctx.cwd.
+    sessionDirs = { projectDir: repoRoot(ctx.cwd) ?? ctx.cwd, launchDir: ctx.cwd }
     const authUi = authUiFor(ctx)
     // The allow/deny lists filter every scope, including a managed-mcp.json set. They
     // merge from managed settings plus the trust-gated settings chain, as Claude
@@ -509,6 +581,9 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   })
 
   pi.on('session_shutdown', async () => {
+    // Closing fires each client's onclose while it is still in the map; the flag
+    // stops those handlers (and any in-flight backoff loop) from reconnecting.
+    shuttingDown = true
     // Close in parallel with a per-client timeout so one hung server can't stall pi's exit.
     await Promise.all([...clients.values()].map((client) => withTimeout(client.close(), 3000, 'close').catch(() => {})))
     // Drop the closed clients and their status now rather than waiting on each client's

package/extensions/mcp/oauth-flow.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { FileOAuthProvider, openBrowser, startCallbackServer, waitForAuthCode } from '../internal/mcp-oauth.js'
+import { FileOAuthProvider, type OAuthServerConfig, openBrowser, startCallbackServer, waitForAuthCode } from '../internal/mcp-oauth.js'
 import { type AuthUi, connectWithTimeout, isUnauthorized, type MakeTransport, OAuthRequiredError } from './transport.js'
 
 /** Browser logins are human-paced; a connect-sized timeout would cut them off. */
@@ -45,13 +45,17 @@ export function serializeInteractiveOAuth<T>(run: () => Promise<T>): Promise<T>
  * token exchange error) is wrapped as an auth failure, not a transport mismatch: that
  * keeps the typeless-url caller from retrying over SSE and prompting for a second login.
  */
-export async function runInteractiveOAuth(name: string, config: { url: string }, makeTransport: MakeTransport, label: string, authUi: AuthUi, newClient: () => Client): Promise<Client> {
+export async function runInteractiveOAuth(name: string, config: { url: string; oauth?: OAuthServerConfig }, makeTransport: MakeTransport, label: string, authUi: AuthUi, newClient: () => Client): Promise<Client> {
   const approved = await authUi.confirm(`MCP server "${name}" requires login`, `Open your browser to authorize ${config.url}?`)
   if (!approved) throw new OAuthRequiredError(`login declined for ${name}`)
-  const provider = new FileOAuthProvider(name, (authorizationUrl) => {
-    openBrowser(String(authorizationUrl))
-    authUi.notify(`Authorize "${name}" in the browser. If it did not open: ${authorizationUrl}`, 'info')
-  })
+  const provider = new FileOAuthProvider(
+    name,
+    (authorizationUrl) => {
+      openBrowser(String(authorizationUrl))
+      authUi.notify(`Authorize "${name}" in the browser. If it did not open: ${authorizationUrl}`, 'info')
+    },
+    config.oauth,
+  )
   const { server, port } = await startCallbackServer(provider.savedRedirectPort())
   provider.bindRedirectPort(port)
   try {

package/extensions/mcp/transport.ts

@@ -5,6 +5,7 @@
  */
 
 import { execFile } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
 // SSE is deprecated in favour of Streamable HTTP, but the SDK notes servers still on
 // the old spec exist, so this stays as a fallback for the migration period.
 import { type OAuthClientProvider, UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js'
@@ -13,8 +14,9 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js' //
 import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js'
-import { FileOAuthProvider } from '../internal/mcp-oauth.js'
-import { expandCwd, interpolateEnv, type ServerConfig, type StdioServerConfig } from './config.js'
+import { ListRootsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { FileOAuthProvider, type OAuthServerConfig } from '../internal/mcp-oauth.js'
+import { expandCwd, type HttpServerConfig, interpolateEnv, type ServerConfig, type StdioServerConfig } from './config.js'
 import { runInteractiveOAuth, serializeInteractiveOAuth } from './oauth-flow.js'
 
 // Claude's MCP_TIMEOUT default: 30 seconds per connect attempt.
@@ -128,6 +130,67 @@ function isStdio(config: ServerConfig): config is StdioServerConfig {
   return 'command' in config && (config.type === undefined || config.type === 'stdio')
 }
 
+/** The session's directories: the launch directory answers roots/list, and the
+ * project root becomes CLAUDE_PROJECT_DIR in a stdio server's environment. */
+export interface SessionDirs {
+  projectDir: string
+  launchDir: string
+}
+
+/** A client that, like Claude, declares the roots capability and answers roots/list
+ * with the session's launch directory. pi's directory set is static, so no
+ * roots/list_changed notification is ever sent. */
+function makeClient(session?: SessionDirs): Client {
+  if (!session) return new Client({ name: 'pi-code-mcp', version: '0.1.0' })
+  const client = new Client({ name: 'pi-code-mcp', version: '0.1.0' }, { capabilities: { roots: {} } })
+  client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: [{ uri: pathToFileURL(session.launchDir).href }] }))
+  return client
+}
+
+/** Claude's credential heuristic for helper environments: any name with TOKEN,
+ * SECRET, PASSWORD, KEY, or AUTH in it in either case (Git's GIT_CONFIG_KEY_<n>
+ * excepted), plus a fixed list of credential names outside the pattern. */
+const CREDENTIAL_NAME_EXTRAS = new Set(['ANTHROPIC_CUSTOM_HEADERS'])
+function isCredentialEnvName(name: string): boolean {
+  if (/^GIT_CONFIG_KEY_\d+$/.test(name)) return false
+  return /TOKEN|SECRET|PASSWORD|KEY|AUTH/i.test(name) || CREDENTIAL_NAME_EXTRAS.has(name)
+}
+
+/** process.env with every credential-named value replaced by REDACTED, used to
+ * expand the url a helper is shown without handing it the credential. */
+function redactedEnv(): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(process.env).map(([key, value]) => [key, isCredentialEnvName(key) ? 'REDACTED' : value]))
+}
+
+/** The environment a headersHelper runs with: Claude's CLAUDE_CODE_MCP_SERVER_NAME
+ * and CLAUDE_CODE_MCP_SERVER_URL (credential-expanded url parts REDACTED), plus
+ * CLAUDE_PLUGIN_ROOT for a plugin's server. A helper a repository or plugin
+ * supplies is a command the user did not write, so it runs without the
+ * credential-named variables; a user-scope helper keeps them. */
+function helperEnv(name: string, config: HttpServerConfig): NodeJS.ProcessEnv {
+  const stripped = config.projectScope === true || config.pluginRoot !== undefined
+  const env: NodeJS.ProcessEnv = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (stripped && isCredentialEnvName(key)) continue
+    env[key] = value
+  }
+  env.CLAUDE_CODE_MCP_SERVER_NAME = name
+  env.CLAUDE_CODE_MCP_SERVER_URL = interpolateEnv(config.url, redactedEnv())
+  if (config.pluginRoot !== undefined) env.CLAUDE_PLUGIN_ROOT = config.pluginRoot
+  return env
+}
+
+/** The env a stdio server process starts with: the SDK allowlist, the config's own
+ * env block, and Claude's path variables (CLAUDE_PROJECT_DIR, and CLAUDE_PLUGIN_ROOT
+ * for a plugin's server). */
+function stdioEnv(config: StdioServerConfig, fill: (value: string) => string, session?: SessionDirs): Record<string, string> {
+  const env: Record<string, string> = { ...getDefaultEnvironment() }
+  for (const [key, value] of Object.entries(config.env ?? {})) env[key] = fill(value)
+  if (session) env.CLAUDE_PROJECT_DIR = session.projectDir
+  if (config.pluginRoot !== undefined) env.CLAUDE_PLUGIN_ROOT = config.pluginRoot
+  return env
+}
+
 export async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
   let timer: ReturnType<typeof setTimeout> | undefined
   const timeout = new Promise<never>((_, reject) => {
@@ -143,8 +206,8 @@ export async function withTimeout<T>(promise: Promise<T>, ms: number, label: str
   }
 }
 
-export async function connect(name: string, config: ServerConfig, authUi?: AuthUi): Promise<Client> {
-  const client = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
+export async function connect(name: string, config: ServerConfig, authUi?: AuthUi, session?: SessionDirs): Promise<Client> {
+  const client = makeClient(session)
   // Names referenced by ${VAR} with no value and no default, gathered across this
   // server's interpolated fields so the connect can warn once rather than fail with a
   // mystery 401 or a command that lost an argument.
@@ -157,12 +220,10 @@ export async function connect(name: string, config: ServerConfig, authUi?: AuthU
     // Start from the SDK's allowlist (PATH, HOME, SHELL, ...) rather than the whole
     // process env: a server should not receive ANTHROPIC_API_KEY or GITHUB_TOKEN just
     // for being launched. A server that needs a variable names it in its own env block.
-    const env: Record<string, string> = { ...getDefaultEnvironment() }
-    for (const [key, value] of Object.entries(config.env ?? {})) env[key] = fill(value)
     const transport = new StdioClientTransport({
       command: fill(config.command),
       args: (config.args ?? []).map((arg) => fill(arg)),
-      env,
+      env: stdioEnv(config, fill, session),
       cwd: expandCwd(config.cwd),
       stderr: 'ignore',
     })
@@ -186,32 +247,68 @@ export async function connect(name: string, config: ServerConfig, authUi?: AuthU
     await connectWithTimeout(client, transport, `connect ${name} (ws)`)
     return client
   }
+  // The SDK's OAuth discovery has no override seam, so a configured metadata URL
+  // cannot be honored; say so instead of silently using standard discovery.
+  if (config.oauth?.authServerMetadataUrl) {
+    console.warn(`pi-code-mcp: server ${name} sets oauth.authServerMetadataUrl, which the MCP SDK cannot override; using standard discovery`)
+  }
   const headers: Record<string, string> = {}
   for (const [key, value] of Object.entries(config.headers ?? {})) headers[key] = fill(value)
   const token = resolveBearerToken(config)
   if (token) headers.Authorization = `Bearer ${token}`
   // A headersHelper generates connect-time headers for non-OAuth auth schemes; its
   // JSON stdout merges over the static headers.
-  if (config.headersHelper) Object.assign(headers, await runHeadersHelper(fill(config.headersHelper)))
+  if (config.headersHelper) Object.assign(headers, await runHeadersHelper(fill(config.headersHelper), helperEnv(name, config)))
   warnMissing()
+  // Claude: a configured Authorization header, whether static, a bearer token, or
+  // helper output, is the server's authentication; there is no OAuth fallback for it.
+  const configuredAuth = Boolean(token) || Object.keys(headers).some((header) => header.toLowerCase() === 'authorization')
   const sseTransport = (authProvider?: OAuthClientProvider) => new SSEClientTransport(url, { requestInit: { headers }, authProvider }) // NOSONAR: explicitly declared or deliberate legacy transport
   if (config.type === 'sse') {
-    return await connectHttpFamily(name, config, sseTransport, `connect ${name} (sse)`, token, authUi)
+    return await connectHttpFamily(name, config, sseTransport, `connect ${name} (sse)`, configuredAuth, authUi, session)
   }
   try {
-    return await connectHttpFamily(name, config, (authProvider) => new StreamableHTTPClientTransport(url, { requestInit: { headers }, authProvider }), `connect ${name}`, token, authUi)
+    return await connectHttpFamily(name, config, (authProvider) => new StreamableHTTPClientTransport(url, { requestInit: { headers }, authProvider }), `connect ${name}`, configuredAuth, authUi, session)
   } catch (error) {
     // An explicitly declared streamable transport must not silently degrade to SSE.
     if (config.type !== undefined || isUnauthorized(error)) throw error
-    return await connectHttpFamily(name, config, sseTransport, `connect ${name} (sse)`, token, authUi)
+    return await connectHttpFamily(name, config, sseTransport, `connect ${name} (sse)`, configuredAuth, authUi, session)
+  }
+}
+
+/** Whether a connect failure is worth retrying: a 5xx response, a refused or reset
+ * connection, or a timeout. Auth and not-found errors need a configuration change. */
+function isTransientConnectError(error: unknown): boolean {
+  if (isUnauthorized(error)) return false
+  const code = typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined
+  if (typeof code === 'number') return code >= 500
+  return /ECONNREFUSED|ECONNRESET|ETIMEDOUT|timed out after/.test(String(error))
+}
+
+const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** Connect with Claude's first-connection retry: an HTTP or SSE server's transient
+ * failure (5xx, connection refused, timeout) is retried up to three times with a
+ * 1s-doubling delay. Stdio and WebSocket connects are attempted once, as are auth
+ * and not-found failures. */
+export async function connectWithRetries(name: string, config: ServerConfig, authUi?: AuthUi, session?: SessionDirs): Promise<Client> {
+  const retriable = !isStdio(config) && config.type !== 'ws' && config.type !== 'websocket'
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await connect(name, config, authUi, session)
+    } catch (error) {
+      if (!retriable || attempt >= 3 || !isTransientConnectError(error)) throw error
+      await delay(1000 * 2 ** attempt)
+    }
   }
 }
 
-/** Run a headersHelper command and parse its JSON stdout into headers. A failure or
- * a 10s timeout yields no extra headers rather than blocking the connection. */
-function runHeadersHelper(command: string): Promise<Record<string, string>> {
+/** Run a headersHelper command and parse its JSON stdout into headers, under the
+ * environment helperEnv built. A failure or a 10s timeout yields no extra headers
+ * rather than blocking the connection. */
+function runHeadersHelper(command: string, env: NodeJS.ProcessEnv): Promise<Record<string, string>> {
   return new Promise((resolve) => {
-    execFile('/bin/sh', ['-c', command], { timeout: 10_000 }, (error, stdout) => {
+    execFile('/bin/sh', ['-c', command], { timeout: 10_000, env }, (error, stdout) => {
       resolve(error ? {} : parseHelperHeaders(stdout))
     })
   })
@@ -229,12 +326,12 @@ export interface AuthUi {
 export class OAuthRequiredError extends Error {}
 
 /** Whether a connect failure is an authentication problem: the SDK's own
- * UnauthorizedError, a transport error carrying HTTP 401 (which is what a 401
- * throws when no authProvider was attached, so a first-time login is detected),
- * or our own marker. */
+ * UnauthorizedError, a transport error carrying HTTP 401 or 403 (Claude: "either
+ * status code flags it" for OAuth), or our own marker. */
 export function isUnauthorized(error: unknown): boolean {
   if (error instanceof UnauthorizedError || error instanceof OAuthRequiredError) return true
-  return typeof error === 'object' && error !== null && (error as { code?: unknown }).code === 401
+  const code = typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined
+  return code === 401 || code === 403
 }
 
 // SSEClientTransport is deprecated in favour of Streamable HTTP, but both concrete
@@ -249,22 +346,25 @@ export type MakeTransport = (authProvider?: OAuthClientProvider) => HttpFamilyTr
  * demands one. Stored tokens ride the first attempt so the SDK refreshes
  * silently; a 401 without tokens asks the user, opens the browser, catches the
  * loopback redirect, and exchanges the code via the SDK's finishAuth.
- * Bearer-token servers never enter the OAuth path: an explicit token is the
- * user saying how auth works.
+ * A server with configured authentication (a bearer token, a static Authorization
+ * header, or one from a headersHelper) never enters the OAuth path: the credential
+ * to fix is the configured one, so an auth failure reports as a failed connection.
  */
-async function connectHttpFamily(name: string, config: { url: string }, makeTransport: MakeTransport, label: string, bearerToken: string | undefined, authUi: AuthUi | undefined): Promise<Client> {
-  const newClient = () => new Client({ name: 'pi-code-mcp', version: '0.1.0' })
+async function connectHttpFamily(name: string, config: { url: string; oauth?: OAuthServerConfig }, makeTransport: MakeTransport, label: string, hasConfiguredAuth: boolean, authUi: AuthUi | undefined, session?: SessionDirs): Promise<Client> {
+  const newClient = () => makeClient(session)
   // Stored tokens ride the first attempt so the SDK refreshes them; with none, no
   // provider is attached, so a 401 surfaces as a transport error carrying code 401
   // (isUnauthorized detects it) and only the interactive provider below ever runs
-  // dynamic registration, keeping it bound to the real callback port.
-  const silent = bearerToken ? undefined : new FileOAuthProvider(name, () => {})
+  // dynamic registration, keeping it bound to the real callback port. A
+  // pre-configured client (oauth.clientId) rides the silent provider too, so its
+  // stored tokens refresh with the configured credentials.
+  const silent = hasConfiguredAuth ? undefined : new FileOAuthProvider(name, () => {}, config.oauth)
   try {
     const client = newClient()
     await connectWithTimeout(client, makeTransport(silent?.hasTokens() ? silent : undefined), label)
     return client
   } catch (error) {
-    if (bearerToken || !isUnauthorized(error)) throw error
+    if (hasConfiguredAuth || !isUnauthorized(error)) throw error
     if (!authUi) throw new OAuthRequiredError(`${name} requires a login; run pi interactively to authenticate`)
     return await serializeInteractiveOAuth(() => runInteractiveOAuth(name, config, makeTransport, label, authUi, newClient))
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, and subagents",
   "keywords": [
     "pi",