From 33d52e6011bc5b9d97231bb41d7ab65806b92df3 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Wed, 4 Nov 2026 17:43:08 -0600 Subject: [PATCH] feat(core): share MCP connections across locations with pool: true (#61185) --- .../client/src/promise/generated/types.ts | 4 + packages/core/src/mcp/client.ts | 125 ++- packages/core/src/mcp/connection.ts | 79 +- packages/core/src/mcp/index.ts | 103 ++- packages/core/src/mcp/oauth.ts | 8 +- packages/core/src/mcp/pool.ts | 377 +++++++++ .../core/test/fixture/mcp-modern-stdio.ts | 15 + .../core/test/fixture/mcp-output-schema.ts | 36 +- packages/core/test/mcp-oauth.test.ts | 62 +- packages/core/test/mcp.test.ts | 751 +++++++++++++++++- packages/protocol/openapi.json | 6 + packages/schema/src/mcp.ts | 8 + ...@modelcontextprotocol%2Fclient@2.3.1.patch | 44 +- services/www/src/docs/content/mcp-servers.mdx | 27 + 14 files changed, 1522 insertions(+), 123 deletions(-) create mode 100644 packages/core/src/mcp/pool.ts create mode 100644 packages/core/test/fixture/mcp-modern-stdio.ts diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index 98cba302a73..877ff90e760 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2448,6 +2448,7 @@ export type ConfigEntry = codemode?: boolean timeout?: { startup?: number; catalog?: number; execution?: number } protocol?: McpProtocol + pool?: boolean } | { type: "remote" @@ -2467,6 +2468,7 @@ export type ConfigEntry = codemode?: boolean timeout?: { startup?: number; catalog?: number; execution?: number } protocol?: McpProtocol + pool?: boolean } } } @@ -4109,6 +4111,7 @@ export type ExperimentalMcpAddInput = { readonly codemode?: boolean readonly timeout?: { readonly startup?: number; readonly catalog?: number; readonly execution?: number } readonly protocol?: "legacy" | "auto" | "2026-07-28" + readonly pool?: boolean } | { readonly type: "remote" @@ -4128,6 +4131,7 @@ export type ExperimentalMcpAddInput = { readonly codemode?: boolean readonly timeout?: { readonly startup?: number; readonly catalog?: number; readonly execution?: number } readonly protocol?: "legacy" | "auto" | "2026-07-28" + readonly pool?: boolean } } diff --git a/packages/core/src/mcp/client.ts b/packages/core/src/mcp/client.ts index b32128dc29e..3db0d64ea01 100644 --- a/packages/core/src/mcp/client.ts +++ b/packages/core/src/mcp/client.ts @@ -26,7 +26,7 @@ import { type Transport, type VersionNegotiationOptions, } from "@modelcontextprotocol/client" -import { Cause, Clock, Duration, Effect, Exit, Schedule, Schema } from "effect" +import { Cause, Clock, Duration, Effect, Exit, PlatformError, Schedule, Schema } from "effect" import { ConfigMCP } from "@opencode/schema/config/mcp" import type { Session } from "@opencode/schema/session" import { isRecord } from "@opencode/util/record" @@ -89,6 +89,8 @@ export class NeedsAuthError extends Schema.TaggedError()("MCP.Ne export class ConnectError extends Schema.TaggedError()("MCP.ConnectError", { server: Schema.String, message: Schema.String, + /** The server was reached but refused or broke the handshake, so different connect options might succeed. */ + answered: Schema.optional(Schema.Boolean), }) {} /** A legacy Streamable HTTP server no longer recognizes this connection's session; the lifecycle reconnects. */ @@ -131,10 +133,21 @@ export interface ElicitationHandler { }) => Effect.Effect } +/** For a request that can come back asking for input: tool calls, prompts and resource reads. */ +export interface PerRequest { + /** + * Answers the elicitations this request causes instead of the connection's handler, for a connection + * that serves several callers. 2026-07-28 only. + */ + readonly elicitation?: ElicitationHandler["create"] +} + /** Handle over a connected MCP server that keeps the SDK `Client` out of the rest of core. */ export interface Connection { /** True when the connection negotiated revision 2026-07-28 or later; false is the initialize handshake. */ readonly modern: boolean + /** The protocol revision the connection negotiated, such as "2025-11-25". */ + readonly protocolVersion: string | undefined /** Display title from `serverInfo.title`, when the server provides one. */ readonly title: string | undefined readonly instructions: string | undefined @@ -143,16 +156,22 @@ export interface Connection { readonly resources: () => Effect.Effect readonly resourceTemplates: () => Effect.Effect /** Resolves to undefined when the server does not advertise resources. */ - readonly readResource: (input: { readonly uri: string }) => Effect.Effect - readonly prompt: (input: { - readonly name: string - readonly args?: Record - }) => Effect.Effect - readonly callTool: (input: { - readonly name: string - readonly args?: Record - readonly sessionID?: Session.ID - }) => Effect.Effect + readonly readResource: ( + input: { readonly uri: string } & PerRequest, + ) => Effect.Effect + readonly prompt: ( + input: { + readonly name: string + readonly args?: Record + } & PerRequest, + ) => Effect.Effect + readonly callTool: ( + input: { + readonly name: string + readonly args?: Record + readonly sessionID?: Session.ID + } & PerRequest, + ) => Effect.Effect readonly onClose: (callback: (reason: string) => void) => void readonly onSessionExpired: (callback: () => void) => void readonly onToolsChanged: (callback: () => void) => void @@ -166,20 +185,28 @@ export interface Attached { readonly transport: Transport } +export interface ConnectOptions { + readonly server: string + readonly config: typeof ConfigMCP.Server.Type | Attached + /** Resolves a relative stdio `cwd` and is the default one, and is the root `roots/list` answers with. */ + readonly directory: string + /** Remote only. A provider with no stored token and a no-op redirect ends in UnauthorizedError → needs_auth. */ + readonly authProvider?: OAuthClientProvider + readonly elicitation?: ElicitationHandler + readonly clientInfo?: Implementation + /** False declares no roots and leaves `roots/list` unanswered, for a connection no one directory owns. */ + readonly roots?: boolean +} + /** * Connects an MCP server; closing the calling scope tears down the transport and any spawned process. * A stdio server is spawned through the location's `Environment`, so it runs wherever the location's * shell commands run rather than always on the host. */ -export const connect = Effect.fnUntraced(function* ( - server: string, - config: typeof ConfigMCP.Server.Type | Attached, - directory: string, - // Remote only. A provider with no stored token and a no-op redirect ends in UnauthorizedError → needs_auth. - authProvider?: OAuthClientProvider, - elicitation?: ElicitationHandler, - clientInfo: Implementation = { name: "opencode", version: "unknown" }, -) { +export const connect = Effect.fnUntraced(function* (options: ConnectOptions) { + const server = options.server + const config = options.config + const elicitation = options.elicitation // The SDK takes list-changed handlers at construction, but consumers register after connect. On a // modern connection the SDK opens the subscriptions/listen stream behind these itself. const timeout: (typeof ConfigMCP.Server.Type)["timeout"] = @@ -193,6 +220,13 @@ export const connect = Effect.fnUntraced(function* ( onChanged: () => changed[key](), }) + // Requests that bring their own elicitation handler, keyed by the signal each passes to the SDK. + const callers = new WeakMap() + const claim = (signal: AbortSignal, input: PerRequest) => { + if (input.elicitation) callers.set(signal, input.elicitation) + return signal + } + // The SDK fails pending requests with a bare "Connection closed"; the transport error before it says why. let lastError: string | undefined const explain = (error: unknown) => @@ -220,12 +254,12 @@ export const connect = Effect.fnUntraced(function* ( const context = yield* Effect.context() const runFork = Effect.runForkWith(context) const runPromise = Effect.runPromiseWith(context) - const client = new Client(clientInfo, { + const client = new Client(options.clientInfo ?? { name: "opencode", version: "unknown" }, { capabilities: { ...(elicitation ? { elicitation: { form: {}, url: {} } } : {}), // Legacy era only: roots are deprecated as of 2026-07-28 and modern servers cannot request them. // Some legacy servers refuse to run without one (https://github.com/anomalyco/opencode/issues/2308). - roots: {}, + ...(options.roots === false ? {} : { roots: {} }), }, versionNegotiation: negotiation(protocol), listChanged: { @@ -240,11 +274,18 @@ export const connect = Effect.fnUntraced(function* ( lastError = describe(error) runFork(Effect.logWarning("mcp transport error", { server, error: lastError })) } - client.setRequestHandler("roots/list", () => ({ roots: [{ uri: pathToFileURL(directory).href }] })) + if (options.roots !== false) + client.setRequestHandler("roots/list", () => ({ roots: [{ uri: pathToFileURL(options.directory).href }] })) if (elicitation) { - client.setRequestHandler("elicitation/create", (request, ctx) => - runPromise(elicitation.create({ server, params: request.params, signal: ctx.mcpReq.signal })), - ) + // A 2026-07-28 server asks for input in the result of the request that needs it. Our SDK patch puts + // that request's options on the context (`mcpReq.origin`, see patches/@modelcontextprotocol%2Fclient), + // so its signal finds the handler it brought. Anything else goes to the connection's handler. + client.setRequestHandler("elicitation/create", (request, ctx) => { + const origin = (ctx.mcpReq as { readonly origin?: { readonly options?: { readonly signal?: AbortSignal } } }) + .origin?.options?.signal + const create = (origin && callers.get(origin)) ?? elicitation.create + return runPromise(create({ server, params: request.params, signal: ctx.mcpReq.signal })) + }) client.setNotificationHandler("notifications/elicitation/complete", (notification) => runPromise(elicitation.complete({ server, elicitationID: notification.params.elicitationId })), ) @@ -289,7 +330,7 @@ export const connect = Effect.fnUntraced(function* ( server, command, args, - cwd: McpStdio.resolveCwd(directory, config.cwd), + cwd: McpStdio.resolveCwd(options.directory, config.cwd), environment: { ...(command === "opencode" ? { BUN_BE_BUN: "1" } : {}), ...config.environment, @@ -298,7 +339,7 @@ export const connect = Effect.fnUntraced(function* ( return yield* initialize(transport) } const { McpOAuth } = yield* Effect.promise(() => import("./oauth.js")) - const fetch = yield* McpOAuth.loggedFetch({ server, directory }) + const fetch = yield* McpOAuth.loggedFetch({ server, directory: options.directory }) // Servers that bundle their own Code Mode (Cloudflare and others) expose raw tools when asked // with ?codemode=false, which is what our Code Mode wants. The configured URL stays the OAuth identity. const url = new URL(config.url) @@ -307,7 +348,7 @@ export const connect = Effect.fnUntraced(function* ( const open = Effect.fnUntraced(function* (url: URL) { session.transport = new StreamableHTTPClientTransport(url, { requestInit: config.headers ? { headers: config.headers } : undefined, - authProvider, + authProvider: options.authProvider, fetch, }) return yield* initialize(session.transport) @@ -373,6 +414,7 @@ export const connect = Effect.fnUntraced(function* ( // Annotated rather than `satisfies`: the inferred SDK types are cyclic, so declaration emit needs the named type. const connection: Connection = { modern: client.getProtocolEra() === "modern", + protocolVersion: client.getNegotiatedProtocolVersion(), title: client.getServerVersion()?.title?.trim() || undefined, instructions: client.getInstructions()?.trim() || undefined, // Tool lists skip the SDK response cache: it re-stringifies every list, and on the first tools/call @@ -453,12 +495,15 @@ export const connect = Effect.fnUntraced(function* ( readResource: (input) => { if (!advertised("resources")) return Effect.succeed(undefined) return request("read MCP resource", (signal) => - client.readResource({ uri: input.uri }, { signal, timeout: execution }), + client.readResource({ uri: input.uri }, { signal: claim(signal, input), timeout: execution }), ) }, prompt: (input) => request("get MCP prompt", (signal) => - client.getPrompt({ name: input.name, arguments: input.args ?? {} }, { signal, timeout: execution }), + client.getPrompt( + { name: input.name, arguments: input.args ?? {} }, + { signal: claim(signal, input), timeout: execution }, + ), ), callTool: (input) => { const call = Effect.tryPromise({ @@ -470,7 +515,7 @@ export const connect = Effect.fnUntraced(function* ( ...(input.sessionID === undefined ? {} : { _meta: { "ai.opencode/sessionID": input.sessionID } }), }, { - signal, + signal: claim(signal, input), timeout: execution, // Only asks for a progress token: progress on the response stream can keep proxies from closing it. // The SDK timeout does not reset on progress; execution is the hard wall. @@ -524,9 +569,23 @@ export const connect = Effect.fnUntraced(function* ( server, message: `${error.message}; the server supports ${error.supported.join(", ")}. Set "protocol" for this server to one of those or to "legacy".`, }) - return yield* new ConnectError({ server, message: explain(error) }) + return yield* new ConnectError({ server, message: explain(error), answered: !repeats(error) }) }) +// Connecting again would fail the same way: the server could not be spawned or reached, did not answer in +// time, is overloaded or down for now, or refused this client's access. A failed auto probe wraps the error it hit. +function repeats(error: unknown): boolean { + if (error instanceof SdkError && error.code === SdkErrorCode.EraNegotiationFailed && error.cause !== undefined) + return repeats(error.cause) + return ( + (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) || + // Refused credentials, even without OAuth: any connection with them would be refused the same way. + (error instanceof SdkHttpError && (error.status === 401 || error.status === 403)) || + isTransient(error) || + PlatformError.isPlatformError(error) + ) +} + // These servers reject any unknown query parameter and have no Code Mode of their own, so adding // ?codemode=false only costs a failed request before the retry at the configured URL. function rejectsUnknownQuery(url: URL) { diff --git a/packages/core/src/mcp/connection.ts b/packages/core/src/mcp/connection.ts index bfbd9df7fea..53290ed3eb1 100644 --- a/packages/core/src/mcp/connection.ts +++ b/packages/core/src/mcp/connection.ts @@ -5,10 +5,18 @@ import type { Mcp } from "@opencode/schema/mcp" import { Cause, Effect, Exit, Scope } from "effect" import { FetchHttpClient } from "effect/http" import { Environment } from "../environment/index.js" +import { KeyedMutex } from "../effect/keyed-mutex.js" import type { McpClient } from "./client.js" export type Failure = Extract +/** A catalog the server can change: its tools, prompts or resources. */ +export type Kind = "tools" | "prompts" | "resources" + +// Unshared connections to one remote endpoint, from any number of Locations, take turns at their +// handshake so the endpoint does not receive a startup burst. +const endpointLoads = KeyedMutex.makeUnsafe() + /** * What a connection reports to its owner. Each runs inline, in order, so the owner can keep its own * state and publish in step with the connection. @@ -18,22 +26,30 @@ export interface Events { readonly connecting: Effect.Effect /** The attempt connected and listed its tools. */ readonly connected: Effect.Effect - readonly failed: (failure: Failure) => Effect.Effect + /** `answered` is true when the server was reached but refused or broke the handshake. */ + readonly failed: (failure: Failure, answered: boolean) => Effect.Effect /** The attempt ended, however it ended. */ readonly settled: Effect.Effect - /** A live connection was torn down. */ - readonly stopped: Effect.Effect /** The live connection closed on its own. Runs under the lock; the owner decides how to stop. */ readonly closed: (reason: string) => Effect.Effect - readonly toolsChanged: Effect.Effect - readonly promptsChanged: Effect.Effect - readonly resourcesChanged: Effect.Effect + /** A catalog changed: the server said so, or the connection was torn down and every catalog emptied. */ + readonly changed: (kind: Kind) => Effect.Effect + /** + * Shared connections only: the server negotiated an older protocol than 2026-07-28, so the attempt closed + * right after the handshake, without listing tools. Reported instead of `connected` or `failed`. + */ + readonly legacy?: (version: string | undefined) => Effect.Effect } export interface Input { readonly name: string readonly config: Mcp.ServerConfig readonly directory: string + /** + * Serves several Locations: it answers no `roots/list`, since no one directory owns it, and skips the + * per-endpoint handshake turn, since it is already the only connection for its key. + */ + readonly shared?: boolean readonly clientInfo?: { readonly name: string; readonly version: string } /** Read on every attempt, so a credential change applies to the next one. */ readonly authProvider: Effect.Effect @@ -46,8 +62,6 @@ export interface Input { readonly scope: Scope.Scope /** Serializes lifecycle work. Callbacks and recovery take it; `start` and `stop` expect the caller to hold it. */ readonly lock: (effect: Effect.Effect) => Effect.Effect - /** Wraps the handshake and initial tool list. */ - readonly handshake: (effect: Effect.Effect) => Effect.Effect /** Runs callbacks from the live connection. */ readonly callbacks: (effect: Effect.Effect) => unknown /** Runs recovery that a background request triggered. */ @@ -110,7 +124,7 @@ export function make(input: Input): Connection { Effect.map((prompts) => { state.prompts = prompts }), - Effect.andThen(input.events.promptsChanged), + Effect.andThen(input.events.changed("prompts")), ) // Re-establishes a connection whose HTTP session the server dropped, unless another path already @@ -141,9 +155,9 @@ export function make(input: Input): Connection { // Background refreshes (list-changed) can observe the expiry too; they do not retry, so // reconnect here for them. Foreground calls reconnect through `recovering`. client.onSessionExpired(() => input.fork(recover(client))) - client.onToolsChanged(() => live(refreshTools(client).pipe(Effect.andThen(input.events.toolsChanged)))) + client.onToolsChanged(() => live(refreshTools(client).pipe(Effect.andThen(input.events.changed("tools"))))) client.onPromptsChanged(() => live(refreshPrompts(client))) - client.onResourcesChanged(() => live(input.events.resourcesChanged)) + client.onResourcesChanged(() => live(input.events.changed("resources"))) } const start: Effect.Effect = Effect.suspend(() => @@ -151,28 +165,44 @@ export function make(input: Input): Connection { yield* input.events.connecting // Checked before the OAuth provider is built, which parses the URL too. if (input.config.type === "remote" && !URL.canParse(input.config.url)) - return yield* input.events.failed({ status: "failed", error: `Invalid MCP server URL: ${input.config.url}` }) + return yield* input.events.failed( + { status: "failed", error: `Invalid MCP server URL: ${input.config.url}` }, + false, + ) const scope = yield* Scope.fork(input.scope) state.scope = scope const authProvider = yield* input.authProvider const { McpClient } = yield* Effect.promise(() => import("./client.js")) // List tools as part of connect so a failure here marks the server failed rather than - // leaving it connected with a silently empty tool list and no path to recover. - const result = yield* McpClient.connect( - input.name, - input.config, - input.directory, + // leaving it connected with a silently empty tool list and no path to recover. A shared connection + // decides first: it can only be shared on 2026-07-28, so an older server is never asked to list. + const config = input.config + const result = yield* McpClient.connect({ + server: input.name, + config, + directory: input.directory, authProvider, - input.elicitation, - input.clientInfo, - ).pipe( - Effect.flatMap((client) => client.tools().pipe(Effect.map((tools) => ({ client, tools })))), + elicitation: input.elicitation, + clientInfo: input.clientInfo, + roots: !input.shared, + }).pipe( + Effect.flatMap( + (client): Effect.Effect<{ client: McpClient.Connection; tools?: ReadonlyArray }, Error> => + input.shared && !client.modern + ? Effect.succeed({ client }) + : client.tools().pipe(Effect.map((tools) => ({ client, tools }))), + ), Effect.provideService(Environment.Service, input.environment), Effect.provideService(FetchHttpClient.Fetch, input.fetch), Scope.provide(scope), - input.handshake, + (effect) => (config.type === "remote" && !input.shared ? endpointLoads.withLock(config.url)(effect) : effect), Effect.exit, ) + if (Exit.isSuccess(result) && !result.value.tools) { + yield* Scope.close(scope, Exit.void) + state.scope = undefined + return yield* input.events.legacy?.(result.value.client.protocolVersion) ?? Effect.void + } if (Exit.isSuccess(result)) { state.client = result.value.client state.tools = result.value.tools @@ -189,6 +219,7 @@ export function make(input: Input): Connection { error instanceof McpClient.NeedsAuthError ? { status: "needs_auth", error: error.message } : { status: "failed", error: error instanceof Error ? error.message : String(error) }, + error instanceof McpClient.ConnectError && error.answered === true, ) }).pipe( Effect.ensuring(input.events.settled), @@ -204,7 +235,9 @@ export function make(input: Input): Connection { state.tools = undefined state.prompts = undefined yield* Scope.close(scope, Exit.void) - yield* input.events.stopped + yield* input.events.changed("tools") + yield* input.events.changed("resources") + yield* input.events.changed("prompts") }) return { diff --git a/packages/core/src/mcp/index.ts b/packages/core/src/mcp/index.ts index fff6b726f40..9571f9727b3 100644 --- a/packages/core/src/mcp/index.ts +++ b/packages/core/src/mcp/index.ts @@ -36,6 +36,7 @@ import { waitForAbort } from "@opencode/util/process" import { State } from "../state.js" import type { McpClient } from "./client.js" import { McpConnection } from "./connection.js" +import { McpPool } from "./pool.js" export const ServerName = Schema.String.pipe(Schema.brand("MCP.ServerName")) export type ServerName = typeof ServerName.Type @@ -126,8 +127,8 @@ const FALLBACK_LIST_TIMEOUT = "5 seconds" // persisted session row, so their forms are owned by this opaque sentinel session identifier. const GLOBAL_ELICITATION_SESSION_ID = "global" const URL_ELICITATION_FIELD_KEY = "elicitation" -// Connections remain Location-scoped, but shared remote endpoints should not receive concurrent startup bursts. -const endpointLoads = KeyedMutex.makeUnsafe() + +const changes = { tools: McpEvent.ToolsChanged, resources: McpEvent.ResourcesChanged, prompts: PromptsChanged } type Data = { servers: Map> @@ -206,6 +207,7 @@ export const layer = (options?: Options) => const integration = yield* Integration.Service const credentials = yield* Credential.Service const fetch = yield* FetchHttpClient.Fetch + const pool = yield* McpPool.Service const root = yield* Effect.scope const fork = yield* FiberSet.makeRuntime() // Server scopes close in parallel on shutdown, so one slow server's stop grace does not delay @@ -286,16 +288,26 @@ export const layer = (options?: Options) => return { entry, client: entry.connection.client } }) - const connectProvider = Effect.fnUntraced(function* (entry: ServerEntry) { + // The credential one start connects with: the integration's latest, or none. Read it once per start and + // pass the result along, so anything keyed on it and the provider it builds agree on the account. + const selectCredential = (entry: ServerEntry) => + entry.config.type === "remote" && entry.integrationID + ? credentials.list(entry.integrationID).pipe(Effect.map((rows) => rows.at(-1))) + : Effect.succeed(undefined) + + const connectProvider = Effect.fnUntraced(function* ( + entry: ServerEntry, + credential: Credential.Info | undefined, + ) { if (entry.config.type !== "remote" || !entry.integrationID) return undefined const { McpOAuth } = yield* Effect.promise(() => import("./oauth.js")) - return yield* McpOAuth.connectProvider({ config: entry.config, integrationID: entry.integrationID }).pipe( + return yield* McpOAuth.connectProvider({ config: entry.config, credential }).pipe( Effect.provideService(Credential.Service, credentials), Effect.provideService(FetchHttpClient.Fetch, fetch), ) }) - const elicitation = { + const elicitation: McpClient.ElicitationHandler = { create: (input: { readonly server: string readonly params: McpClient.ElicitationParams @@ -336,7 +348,7 @@ export const layer = (options?: Options) => const [field, ...fields] = Object.entries(params.requestedSchema.properties).map(([key, property]) => toElicitationField(key, property, params.requestedSchema.required?.includes(key) === true), ) - if (!field) return { action: "accept", content: {} } + if (!field) return { action: "accept" as const, content: {} } return yield* forms .ask({ sessionID: GLOBAL_ELICITATION_SESSION_ID, @@ -359,33 +371,62 @@ export const layer = (options?: Options) => } }), ) - }), + }).pipe( + // A shared connection runs its handlers outside this Location; forms must still belong to it. + Effect.provideService(Location.Service, location), + ), complete: (input: { readonly server: string; readonly elicitationID: string }) => Effect.gen(function* () { const formID = urlElicitations.get(input.server + "\u0000" + input.elicitationID) if (!formID) return yield* forms.reply({ id: formID, answer: { [URL_ELICITATION_FIELD_KEY]: true } }).pipe(Effect.ignore) }), - } satisfies McpClient.ElicitationHandler + } const makeEntry = (name: ServerName, config: Mcp.ServerConfig, started: number): ServerEntry => { + // Local servers run on this Location's execution plane, so only Locations on the host share them. + const pooled = + config.pool === true && + config.protocol !== "legacy" && + (config.type === "remote" || location.workspaceID === undefined) + const share = (input: McpConnection.Input) => + pool.connection({ + ...input, + select: Effect.gen(function* () { + if (input.config.type === "remote") { + const credential = yield* selectCredential(entry) + return { + key: McpPool.key({ ...input, credential: credential?.id }), + authProvider: connectProvider(entry, credential), + } + } + // Resolved exactly as the spawn resolves it, `~` included, so the key matches where the server runs. + const { McpStdio } = yield* Effect.promise(() => import("./stdio.js")) + return { + key: McpPool.key({ ...input, cwd: McpStdio.resolveCwd(input.directory, input.config.cwd) }), + authProvider: input.authProvider, + } + }), + }) const entry: ServerEntry = { config, status: { status: "pending" }, startup: Latch.makeUnsafe(), attempt: { started, settled: Latch.makeUnsafe() }, - connection: McpConnection.make({ + connection: (pooled ? share : McpConnection.make)({ name, - config, + // Pooling offers 2026-07-28, the only revision a connection can be shared on. + config: config.pool && config.protocol === undefined ? { ...config, protocol: "auto" } : config, directory: location.directory, clientInfo: options?.clientInfo, - authProvider: Effect.suspend(() => connectProvider(entry)), + authProvider: Effect.suspend(() => + selectCredential(entry).pipe(Effect.flatMap((credential) => connectProvider(entry, credential))), + ), elicitation, environment, fetch, scope: servers, lock: locks.withLock(name), - handshake: (effect) => (config.type === "remote" ? endpointLoads.withLock(config.url)(effect) : effect), callbacks, fork, events: { @@ -401,9 +442,12 @@ export const layer = (options?: Options) => connected: Effect.gen(function* () { entry.status = { status: "connected" } yield* Effect.logInfo("mcp connected", { server: name, tools: entry.connection.tools?.length }) - // The tool registry reads on this event; a late-connecting server has no other way to appear. + // Announce every list a consumer may read, since each reads them only on these events. A + // connection another Location already holds has loaded its prompts, and no later change + // would tell this one; prompts still loading read empty now and announce themselves later. yield* bus.publish(McpEvent.ToolsChanged, { server: name }) yield* bus.publish(McpEvent.ResourcesChanged, { server: name }) + yield* bus.publish(PromptsChanged, { server: name }) yield* bus.publish(McpEvent.StatusChanged, { server: name }) }), failed: (failure) => @@ -418,20 +462,13 @@ export const layer = (options?: Options) => entry.attempt = undefined return (attempt ? attempt.settled.open : Effect.void).pipe(Effect.ensuring(entry.startup.open)) }), - stopped: Effect.gen(function* () { - yield* bus.publish(McpEvent.ToolsChanged, { server: name }) - yield* bus.publish(McpEvent.ResourcesChanged, { server: name }) - yield* bus.publish(PromptsChanged, { server: name }) - }), closed: (reason) => Effect.gen(function* () { entry.status = { status: "failed", error: reason } yield* entry.connection.stop yield* bus.publish(McpEvent.StatusChanged, { server: name }) }), - toolsChanged: bus.publish(McpEvent.ToolsChanged, { server: name }), - promptsChanged: bus.publish(PromptsChanged, { server: name }), - resourcesChanged: bus.publish(McpEvent.ResourcesChanged, { server: name }), + changed: (kind) => bus.publish(changes[kind], { server: name }), }, }), } @@ -553,14 +590,13 @@ export const layer = (options?: Options) => // interruption or Location shutdown) must still close the transport right away. yield* Scope.addFinalizer(scope, Effect.promise(() => transport.close()).pipe(Effect.ignore)) let closed = false - const result = yield* McpClient.connect( - name, - { type: "attached", transport }, - location.directory, - undefined, + const result = yield* McpClient.connect({ + server: name, + config: { type: "attached", transport }, + directory: location.directory, elicitation, - options?.clientInfo, - ).pipe( + clientInfo: options?.clientInfo, + }).pipe( Effect.tap((connection) => Effect.sync(() => connection.onClose(() => { @@ -887,7 +923,16 @@ export function configured(options?: Options) { return makeLocationNode({ service: Service, layer: layer(options), - deps: [Location.node, Environment.node, Bus.node, Form.node, Integration.node, Credential.node, httpFetch], + deps: [ + Location.node, + Environment.node, + Bus.node, + Form.node, + Integration.node, + Credential.node, + httpFetch, + McpPool.node, + ], }) } diff --git a/packages/core/src/mcp/oauth.ts b/packages/core/src/mcp/oauth.ts index f79935ee737..63a005a48af 100644 --- a/packages/core/src/mcp/oauth.ts +++ b/packages/core/src/mcp/oauth.ts @@ -282,14 +282,18 @@ const toTokens = (credential: Credential.OAuth): StoredOAuthTokens => { } } +/** + * A provider for one credential the caller already selected, or none. It never looks up the active credential + * itself: it reads and refreshes only the selected row, and a provider made without one stays anonymous. + */ export const connectProvider = Effect.fnUntraced(function* (input: { readonly config: typeof ConfigMCP.Remote.Type - readonly integrationID: Integration.ID + readonly credential: Credential.Info | undefined }) { const credentials = yield* Credential.Service const run = Effect.runPromiseWith(yield* Effect.context()) const fetch = yield* sender - const found = (yield* credentials.list(input.integrationID)).at(-1) + const found = input.credential if (!found || found.value.type !== "oauth") return provider({ config: input.config, store: memoryStore(), fetch }) const id = found.id const methodID = found.value.methodID diff --git a/packages/core/src/mcp/pool.ts b/packages/core/src/mcp/pool.ts new file mode 100644 index 00000000000..5a4841d6ca1 --- /dev/null +++ b/packages/core/src/mcp/pool.ts @@ -0,0 +1,377 @@ +export * as McpPool from "./pool.js" + +import type { OAuthClientProvider } from "@modelcontextprotocol/client" +import type { Mcp } from "@opencode/schema/mcp" +import { CrossSpawnSpawner } from "@opencode/util/cross-spawn-spawner" +import { makeGlobalNode } from "@opencode/util/effect/app-node" +import { httpFetch } from "@opencode/util/effect/app-node-platform" +import { Cause, Context, Deferred, Effect, Exit, Fiber, FiberSet, Layer, Scope, Semaphore } from "effect" +import { FetchHttpClient } from "effect/http" +import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner" +import { Environment } from "../environment/index.js" +import { SharedCache } from "../shared-cache.js" +import type { McpClient } from "./client.js" +import { McpConnection } from "./connection.js" + +export interface Input extends McpConnection.Input { + /** + * Run once per start: what tells this connection apart from every other one to the same server (see `key`), + * and the OAuth provider to open it with. Both come from one credential selection, so a slot's key and the + * account it connects as can't disagree. + */ + readonly select: Effect.Effect +} + +export interface Selection { + readonly key: string + readonly authProvider: Effect.Effect +} + +export interface Interface { + /** + * A Location's connection to a server that may be shared. Each start joins the connection other + * Locations hold under the same key, or opens it, and each stop lets go of it; the last to let go + * closes it. A server that negotiates the legacy protocol, or that answers but refuses or breaks the + * pooled handshake, is never shared: the Location connects on its own, exactly as it would unpooled, + * and every later start for that key skips straight to that. + */ + readonly connection: (input: Input) => McpConnection.Connection +} + +export class Service extends Context.Service()("@opencode/McpPool") {} + +/** + * Everything that could make two connections behave differently, so only identical ones are shared. + * The server's name is left out; each Location keeps its own. Secrets appear only as fingerprints. + */ +export const key = (input: { + readonly config: Mcp.ServerConfig + /** Local only: the directory the server runs in, as `McpStdio.resolveCwd` resolves it for the spawn. */ + readonly cwd?: string + /** The active OAuth credential's ID, which a token refresh keeps and a sign-in replaces. */ + readonly credential?: string + readonly clientInfo?: { readonly name: string; readonly version: string } +}) => { + const config = input.config + const common = [config.protocol, config.timeout ?? null, input.clientInfo ?? null] + if (config.type === "remote") + return JSON.stringify([ + "remote", + config.url, + fingerprint(config.headers), + config.oauth ? { ...config.oauth, client_secret: fingerprint(config.oauth.client_secret) } : config.oauth, + // A remote server's URL gains ?codemode=false unless Code Mode is off. + config.codemode !== false, + input.credential ?? null, + ...common, + ]) + // Only Locations on this host share local servers, so the execution plane is always the host. + return JSON.stringify([ + "local", + "host", + config.command, + input.cwd ?? null, + fingerprint(config.environment), + ...common, + ]) +} + +function fingerprint(secret: string | Record | undefined) { + if (secret === undefined) return null + return SharedCache.fingerprint( + typeof secret === "string" + ? secret + : JSON.stringify(Object.entries(secret).toSorted(([a], [b]) => a.localeCompare(b))), + ) +} + +// A Location holding a shared connection. The pool reaches Locations only through the holders +// registered right now, never through the one that opened the connection. +interface Holder { + readonly authProvider: Effect.Effect + readonly elicitation: McpClient.ElicitationHandler["create"] + readonly closed: (reason: string) => void + readonly changed: (kind: McpConnection.Kind) => void +} + +type Outcome = "connected" | "private" | McpConnection.Failure + +interface Slot { + readonly connection: McpConnection.Connection + readonly holders: Set + readonly lock: Semaphore.Semaphore + readonly outcome: Deferred.Deferred + start?: Fiber.Fiber + connected: boolean +} + +export const layer = Layer.effect( + Service, + Effect.gen(function* () { + const scope = yield* Effect.scope + const run = yield* FiberSet.makeRuntime() + const driver = Environment.makeLocalDriver(yield* ChildProcessSpawner) + const host = Environment.Service.of({ files: Environment.makeFiles(driver), spawner: driver.spawner }) + const fetch = yield* FetchHttpClient.Fetch + const slots = new Map() + // Keys whose server negotiated legacy or refused the pooled handshake. Kept for the life of the process. + const unpoolable = new Set() + // The subset that negotiated legacy. Their private connections skip the 2026-07-28 probe; a refusal + // proves nothing about the protocol, so those keep the configured one. + const legacy = new Set() + // Names of local servers already warned about for having no cwd, which keeps each project's folder in the key. + const unfixed = new Set() + + // Takes only data from the Location that opens it: the connection outlives that Location's claim. + const open = (key: string, input: Pick) => { + const slot: Slot = { + holders: new Set(), + lock: Semaphore.makeUnsafe(1), + outcome: Deferred.makeUnsafe(), + connected: false, + connection: McpConnection.make({ + name: input.name, + config: input.config, + directory: input.directory, + shared: true, + clientInfo: input.clientInfo, + // Every holder of a key presents the same credential, so any of them can build the provider. + authProvider: Effect.suspend(() => slot.holders.values().next().value?.authProvider ?? Effect.undefined), + elicitation: { + // Elicitations a request carries reach that request's Location. Any other one, which the + // server could not tie to a request, goes to every holder and the first answer wins; the + // others are interrupted, which cancels their forms. + create: (request) => + Effect.suspend(() => { + const holders = Array.from(slot.holders) + if (holders.length === 0) return Effect.succeed({ action: "cancel" as const }) + return Effect.raceAll(holders.map((holder) => holder.elicitation(request))) + }), + complete: () => Effect.void, + }, + environment: host, + fetch, + scope, + lock: (effect) => slot.lock.withPermit(effect), + callbacks: run, + fork: run, + events: { + connecting: Effect.void, + connected: Effect.void, + // A server that answered but refused the pooled handshake, such as one that wants roots, may + // still accept the Location's own connection; anything unreachable would only fail again. + failed: (failure, answered) => + Effect.gen(function* () { + detach(key, slot) + if (answered) { + unpoolable.add(key) + yield* Effect.logWarning("mcp pool ignored: server refused the shared connection", { + server: input.name, + error: failure.error, + }) + } + yield* Deferred.succeed(slot.outcome, answered ? "private" : failure) + }), + legacy: (version) => + Effect.gen(function* () { + detach(key, slot) + unpoolable.add(key) + legacy.add(key) + yield* Effect.logWarning("mcp pool ignored: server speaks an older protocol", { + server: input.name, + version, + }) + yield* Deferred.succeed(slot.outcome, "private") + }), + settled: Effect.void, + closed: (reason) => + Effect.gen(function* () { + detach(key, slot) + const holders = Array.from(slot.holders) + slot.holders.clear() + yield* slot.connection.stop + for (const holder of holders) holder.closed(reason) + }), + changed: (kind) => + Effect.sync(() => { + if (slot.connected) for (const holder of slot.holders) holder.changed(kind) + }), + }, + }), + } + slots.set(key, slot) + return slot + } + + const connect = (key: string, slot: Slot) => + Effect.gen(function* () { + yield* slot.connection.start + // A failed or legacy start already settled the outcome. + if (!slot.connection.client) return + slot.connected = true + yield* Deferred.succeed(slot.outcome, "connected") + }).pipe( + slot.lock.withPermit, + // Holders wait on the outcome, so an attempt that dies still settles it. + Effect.onError((cause) => + Effect.suspend(() => { + detach(key, slot) + return Deferred.succeed(slot.outcome, { status: "failed", error: String(Cause.squash(cause)) }) + }), + ), + ) + + const detach = (key: string, slot: Slot) => { + if (slots.get(key) === slot) slots.delete(key) + } + + // Closes as soon as the last holder lets go, interrupting a start nobody waits for anymore. + const release = (key: string, slot: Slot, holder: Holder) => + Effect.suspend(() => { + slot.holders.delete(holder) + if (slot.holders.size > 0) return Effect.void + detach(key, slot) + return Effect.gen(function* () { + if (slot.start) yield* Fiber.interrupt(slot.start) + yield* slot.connection.stop.pipe(slot.lock.withPermit) + }) + }) + + const acquire = Effect.fnUntraced(function* (key: string, input: Input, holder: Holder) { + if (unpoolable.has(key)) return "private" as const + const slot = + slots.get(key) ?? + open(key, { name: input.name, config: input.config, directory: input.directory, clientInfo: input.clientInfo }) + yield* Effect.acquireRelease( + Effect.sync(() => slot.holders.add(holder)), + () => release(key, slot, holder), + ) + // Started once a holder is registered: the attempt reads its OAuth provider from the holders. + slot.start ??= run(connect(key, slot)) + const outcome = yield* Deferred.await(slot.outcome) + return outcome === "connected" ? slot.connection : outcome + }) + + const connection = (input: Input): McpConnection.Connection => { + const state: { + claim?: Scope.Closeable + holder?: Holder + shared?: McpConnection.Connection + own?: McpConnection.Connection + // This start's credential selection, which a private connection opens with as well. + selected?: Selection + } = {} + // A private connection, used when the key can't be shared, with the configured protocol or plain legacy. + const privately = (config: Mcp.ServerConfig) => + McpConnection.make({ + ...input, + config, + authProvider: Effect.suspend(() => state.selected?.authProvider ?? input.authProvider), + }) + const configured = privately(input.config) + const older = privately({ ...input.config, protocol: "legacy" }) + const live = () => state.shared ?? state.own ?? configured + // The shared connection carries the name of the Location that opened it; forms show this Location's. + const elicit: McpClient.ElicitationHandler["create"] = (request) => + input.elicitation.create({ ...request, server: input.name }) + + // Holder callbacks run in the Location's own callback runtime, under its lock, and only while the + // claim they belong to is the current one. + const current = (holder: Holder, effect: () => Effect.Effect) => + input.callbacks( + Effect.suspend(() => (state.holder === holder ? effect() : Effect.void)).pipe(input.lock, Effect.ignore), + ) + + const clear = Effect.suspend(() => { + const claim = state.claim + state.claim = undefined + state.holder = undefined + state.shared = undefined + return claim ? Scope.close(claim, Exit.void) : Effect.void + }) + + // Resolves false when the key can't be shared, leaving the start to the Location's own connection. + const join = (selected: Selection) => + Effect.gen(function* () { + yield* input.events.connecting + const claim = yield* Scope.fork(input.scope) + const holder: Holder = { + authProvider: selected.authProvider, + elicitation: elicit, + closed: (reason) => current(holder, () => input.events.closed(reason)), + changed: (kind) => current(holder, () => input.events.changed(kind)), + } + state.claim = claim + state.holder = holder + const outcome = yield* acquire(selected.key, input, holder).pipe( + Scope.provide(claim), + Effect.onInterrupt(() => clear), + ) + if (outcome === "private") { + yield* clear + return false + } + if ("status" in outcome) { + yield* clear + yield* input.events.failed(outcome, false) + return true + } + state.shared = outcome + yield* input.events.connected + return true + }).pipe(Effect.onExit((exit) => (Exit.isSuccess(exit) && !exit.value ? Effect.void : input.events.settled))) + + // Requests through a shared connection bring this Location's elicitation handler along. + const bind = (client: McpClient.Connection): McpClient.Connection => ({ + ...client, + callTool: (request) => client.callTool({ elicitation: elicit, ...request }), + prompt: (request) => client.prompt({ elicitation: elicit, ...request }), + readResource: (request) => client.readResource({ elicitation: elicit, ...request }), + }) + + return { + get client() { + return live().client + }, + get tools() { + return live().tools + }, + get prompts() { + return live().prompts + }, + start: Effect.gen(function* () { + if (input.config.type === "local" && input.config.cwd === undefined && !unfixed.has(input.name)) { + unfixed.add(input.name) + yield* Effect.logWarning( + "mcp pool ignored: local server has no fixed cwd, so each directory runs its own", + { + server: input.name, + }, + ) + } + const selected = yield* input.select + state.selected = selected + if (!unpoolable.has(selected.key) && (yield* join(selected))) return + state.own = legacy.has(selected.key) ? older : configured + yield* state.own.start + }), + stop: Effect.gen(function* () { + if (!state.claim) return yield* (state.own ?? configured).stop + yield* clear + yield* input.events.changed("tools") + yield* input.events.changed("resources") + yield* input.events.changed("prompts") + }), + recovering: (client, request) => + state.shared + ? state.shared.recovering(client, (client) => request(bind(client))) + : (state.own ?? configured).recovering(client, request), + catalog: (client) => live().catalog(client), + } + } + + return Service.of({ connection }) + }), +) + +export const node = makeGlobalNode({ service: Service, layer, deps: [CrossSpawnSpawner.node, httpFetch] }) diff --git a/packages/core/test/fixture/mcp-modern-stdio.ts b/packages/core/test/fixture/mcp-modern-stdio.ts new file mode 100644 index 00000000000..efc1031b835 --- /dev/null +++ b/packages/core/test/fixture/mcp-modern-stdio.ts @@ -0,0 +1,15 @@ +import { appendFileSync } from "node:fs" +import { Server } from "@modelcontextprotocol/server" +import { serveStdio } from "@modelcontextprotocol/server/stdio" + +// A stdio server that speaks 2026-07-28, appending its pid to MCP_PID_FILE so a test can count and stop processes. +if (process.env.MCP_PID_FILE) appendFileSync(process.env.MCP_PID_FILE, `${process.pid}\n`) + +serveStdio(() => { + const server = new Server({ name: "modern-stdio", version: "1.0.0" }, { capabilities: { tools: {} } }) + server.setRequestHandler("tools/list", () => + Promise.resolve({ tools: [{ name: "echo", inputSchema: { type: "object" as const, properties: {} } }] }), + ) + server.setRequestHandler("tools/call", () => Promise.resolve({ content: [{ type: "text", text: "ok" }] })) + return server +}) diff --git a/packages/core/test/fixture/mcp-output-schema.ts b/packages/core/test/fixture/mcp-output-schema.ts index 5d562a0d030..1aec8c897a8 100644 --- a/packages/core/test/fixture/mcp-output-schema.ts +++ b/packages/core/test/fixture/mcp-output-schema.ts @@ -1,10 +1,14 @@ -import { Server } from "@modelcontextprotocol/server" +import { isInitializeRequest, Server } from "@modelcontextprotocol/server" import { StdioServerTransport } from "@modelcontextprotocol/server/stdio" +import { appendFileSync } from "node:fs" const server = new Server({ name: "output-schema", version: "1.0.0" }, { capabilities: { tools: {} } }) -server.setRequestHandler("tools/list", ({ params }) => - Promise.resolve( +server.setRequestHandler("tools/list", ({ params }) => { + // Like servers that only need a root once asked for their tools. + if (process.env.MCP_REQUIRE_ROOTS_TO_LIST && !server.getClientCapabilities()?.roots) + return Promise.reject(new Error("a root is required to list tools")) + return Promise.resolve( params?.cursor === "page-2" ? { tools: [ @@ -33,7 +37,27 @@ server.setRequestHandler("tools/list", ({ params }) => ], nextCursor: "page-2", }, - ), -) + ) +}) -await server.connect(new StdioServerTransport()) +const transport = new StdioServerTransport() +await server.connect(transport) + +// Appends the method of every message the server receives, so a test can count requests across processes. +if (process.env.MCP_WIRE_LOG) { + const log = process.env.MCP_WIRE_LOG + const receive = transport.onmessage + transport.onmessage = (message) => { + appendFileSync(log, `${"method" in message ? message.method : "response"}\n`) + receive?.(message) + } +} + +// Like servers that refuse to run without a root (https://github.com/anomalyco/opencode/issues/2308). +if (process.env.MCP_REQUIRE_ROOTS) { + const receive = transport.onmessage + transport.onmessage = (message) => { + if (isInitializeRequest(message) && !message.params.capabilities.roots) process.exit(1) + receive?.(message) + } +} diff --git a/packages/core/test/mcp-oauth.test.ts b/packages/core/test/mcp-oauth.test.ts index 0ae87f94d6c..e91ff285607 100644 --- a/packages/core/test/mcp-oauth.test.ts +++ b/packages/core/test/mcp-oauth.test.ts @@ -55,7 +55,9 @@ const memoryCredentials = (initial: Credential.Info[]) => { const connectProvider = (config: typeof ConfigMCP.Remote.Type, store: ReturnType) => Effect.runPromise( - McpOAuth.connectProvider({ config, integrationID }).pipe(Effect.provideService(Credential.Service, store.service)), + McpOAuth.connectProvider({ config, credential: Array.from(store.rows.values()).at(-1) }).pipe( + Effect.provideService(Credential.Service, store.service), + ), ) // Serves authorization server metadata with the given capabilities and records DCR + token requests. @@ -287,6 +289,57 @@ describe("MCP OAuth", () => { expect(stored?.type === "oauth" && stored.metadata?.issuer).toBe(server.url.href) }) + test("refreshes the credential it was made with, not the one signed in since", async () => { + const server = Bun.serve({ + port: 0, + async fetch(request) { + const url = new URL(request.url) + if (request.method !== "POST" || url.pathname !== "/token") return new Response(null, { status: 404 }) + const refresh = new URLSearchParams(await request.text()).get("refresh_token") + return Response.json({ access_token: `next-for-${refresh}`, token_type: "Bearer" }) + }, + }) + const selected = credential({ access: "expired", refresh: "refresh", url: server.url.href }) + const newer = new Credential.Info({ + ...credential({ + access: "other", + refresh: "other-refresh", + url: server.url.href, + expires: Date.now() + 3_600_000, + }), + id: Credential.ID.make("cred_newer"), + }) + const store = memoryCredentials([selected, newer]) + const oauthProvider = await Effect.runPromise( + McpOAuth.connectProvider({ config: remote(server.url.href), credential: selected }).pipe( + Effect.provideService(Credential.Service, store.service), + ), + ) + + const result = await auth(oauthProvider, { serverUrl: server.url.href }).finally(() => server.stop(true)) + + expect(result).toBe("AUTHORIZED") + expect((await oauthProvider.tokens())?.access_token).toBe("next-for-refresh") + const stored = store.rows.get(selected.id)?.value + expect(stored?.type === "oauth" && stored.access).toBe("next-for-refresh") + const untouched = store.rows.get(newer.id)?.value + expect(untouched?.type === "oauth" && untouched.access).toBe("other") + }) + + test("stays anonymous when made without a credential, even after one is signed in", async () => { + const store = memoryCredentials([]) + const oauthProvider = await Effect.runPromise( + McpOAuth.connectProvider({ config: remote(authServer.url.href), credential: undefined }).pipe( + Effect.provideService(Credential.Service, store.service), + ), + ) + store.rows.set( + Credential.ID.make("cred_test"), + credential({ access: "late", refresh: "late", url: authServer.url.href }), + ) + expect(await oauthProvider.tokens()).toBeUndefined() + }) + test("reports needs_auth for an unauthorized server without registering a client", async () => { let registrations = 0 const server = Bun.serve({ @@ -302,10 +355,9 @@ describe("MCP OAuth", () => { const oauthProvider = await connectProvider(config, memoryCredentials([])) const exit = await Effect.runPromise( - Effect.scoped(McpClient.connect("test", config, import.meta.dir, oauthProvider)).pipe( - Effect.provide(hostEnvironmentLayer), - Effect.exit, - ), + Effect.scoped( + McpClient.connect({ server: "test", config, directory: import.meta.dir, authProvider: oauthProvider }), + ).pipe(Effect.provide(hostEnvironmentLayer), Effect.exit), ).finally(() => server.stop(true)) const error = Exit.isFailure(exit) && Cause.squash(exit.cause) diff --git a/packages/core/test/mcp.test.ts b/packages/core/test/mcp.test.ts index 2d6044a7f0c..2b7d5e32f28 100644 --- a/packages/core/test/mcp.test.ts +++ b/packages/core/test/mcp.test.ts @@ -34,12 +34,15 @@ import { EnvironmentUnavailable } from "@opencode/core/environment/unavailable" import { Location } from "@opencode/core/location" import { Mcp } from "@opencode/core/mcp/index" import { McpClient } from "@opencode/core/mcp/client" +import { McpPool } from "@opencode/core/mcp/pool" import { McpStdio } from "@opencode/core/mcp/stdio" import { Permission } from "@opencode/core/permission" import { AbsolutePath } from "@opencode/core/schema" import { Session } from "@opencode/core/session" import { State } from "@opencode/core/state" import { McpTool } from "@opencode/core/tool/mcp" +import { Command } from "@opencode/core/command" +import { CommandPlugin } from "@opencode/core/plugin/command" import { McpResourceTools } from "@opencode/core/tool/plugin/mcp-resource" import { Tool } from "@opencode/core/tool" import { ToolOutput } from "@opencode/core/tool-output" @@ -49,13 +52,16 @@ import { Effect, Exit, Fiber, + FiberSet, Layer, + Logger, Option, PubSub, Ref, Schedule, Schema, Scope, + Semaphore, Sink, Stream, } from "effect" @@ -64,11 +70,14 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process" import { ExitCode, makeHandle, ProcessId } from "effect/process/ChildProcessSpawner" import { Image } from "@opencode/core/image" import { Global } from "@opencode/util/global" +import { isRecord } from "@opencode/util/record" +import { CrossSpawnSpawner } from "@opencode/util/cross-spawn-spawner" import { advance, drain } from "./lib/clock" import { testEffect } from "./lib/effect" import { registerIntegrationPolicy, setOrganizationPolicy } from "./fixture/policy" import { imagePassthrough } from "./lib/image" import { location } from "./fixture/location" +import { host } from "./plugin/host" import { tmpdirScoped } from "./fixture/tmpdir" import { hostEnvironmentLayer, recordingEnvironmentLayer } from "./fixture/environment" import { @@ -113,6 +122,8 @@ function resourceServer( tools?: ListToolsResult["tools"] /** Legacy servers give up on the URL elicitation after this many milliseconds. */ elicitationTimeout?: number + /** Lists a `roots` tool that asks for the client's roots (2026-07-28 only) and returns them. */ + roots?: boolean respond?: (request: Request) => Response | undefined | Promise } = {}, ) { @@ -140,6 +151,8 @@ function resourceServer( progressToken: unknown }>, initializations: 0, + /** Listed after the configured tools; change it, then announce the change. */ + extraTools: [] as ListToolsResult["tools"], urls: [] as string[], sessions: [] as string[], } @@ -150,7 +163,7 @@ function resourceServer( { name: "mcp-resources", title: "MCP Resources", version: "1.0.0" }, { capabilities: { - tools: {}, + tools: { listChanged: input.listChanged }, prompts: {}, ...(input.resources === false ? {} : { resources: { listChanged: input.listChanged } }), }, @@ -198,6 +211,8 @@ function resourceServer( ? [{ name: "url-elicitation", inputSchema: { type: "object" as const, properties: {} } }] : [{ name: "echo", inputSchema: { type: "object" as const, properties: {} } }]), ...(input.tools ?? []), + ...(input.roots ? [{ name: "roots", inputSchema: { type: "object" as const, properties: {} } }] : []), + ...state.extraTools, ], }) }) @@ -240,7 +255,13 @@ function resourceServer( }) } if (!input.emptyElicitation && !input.urlElicitation) { - protocol.setRequestHandler("tools/call", (request) => { + protocol.setRequestHandler("tools/call", (request, ctx) => { + if (request.params.name === "roots") { + const responses = ctx.mcpReq.inputResponses + if (!responses) + return Promise.resolve(inputRequired({ inputRequests: { roots: inputRequired.listRoots() } })) + return Promise.resolve({ content: [], structuredContent: inputResponse(responses, "roots") }) + } state.toolCalls.push({ name: request.params.name, arguments: request.params.arguments, @@ -307,6 +328,8 @@ function resourceServer( state, url: http.url.toString(), clientVersion: () => current.protocol.getClientVersion(), + sendToolListChanged: () => + modern ? Promise.resolve(modern.notify.toolsChanged()) : current.protocol.sendToolListChanged(), sendResourceListChanged: () => modern ? Promise.resolve(modern.notify.resourcesChanged()) : current.protocol.sendResourceListChanged(), completeElicitation: () => current.protocol.createElicitationCompletionNotifier("elicitation-test")(), @@ -325,6 +348,8 @@ function resourceServer( ) } +const poolLayer = McpPool.layer.pipe(Layer.provide(LayerNode.compile(CrossSpawnSpawner.node))) + function resourceMcpLayer( server: string | typeof ConfigMCP.Server.Type, onFormCreated?: (form: Form.Info) => Effect.Effect, @@ -335,9 +360,15 @@ function resourceMcpLayer( subscribe?: Bus.Interface["subscribe"] environment?: Layer.Layer published?: string[] + pool?: Layer.Layer + directory?: string + /** The configured server's name; "resources" unless given. */ + name?: string + credentials?: Partial + bus?: Layer.Layer }, ) { - const directory = AbsolutePath.make(import.meta.dir) + const directory = AbsolutePath.make(overrides?.directory ?? import.meta.dir) const unusedIntegration = () => Effect.die("unused integration service") const entries = overrides?.entries return Layer.effectDiscard( @@ -356,6 +387,7 @@ function resourceMcpLayer( Layer.provideMerge(Form.layer), Layer.provide( Layer.mergeAll( + overrides?.pool ?? poolLayer, entries ? Layer.succeed( Config.Service, @@ -368,7 +400,7 @@ function resourceMcpLayer( policies: overrides?.policies ?? [], mcp: new ConfigMCP.Info({ servers: { - resources: + [overrides?.name ?? "resources"]: typeof server === "string" ? new ConfigMCP.Remote({ type: "remote", url: server, oauth: false }) : server, @@ -378,20 +410,23 @@ function resourceMcpLayer( }), ]), Layer.succeed(Location.Service, Location.Service.of(location({ directory }))), - Layer.mock(Bus.Service, { - subscribe: overrides?.subscribe ?? (() => Stream.never), - publish: (definition, data) => - Effect.suspend(() => { - const event = { - id: ID.create(), - type: definition.type, - data, - } as Payload - overrides?.published?.push(event.type) - if (event.type !== Form.Event.Created.type || !onFormCreated) return Effect.succeed(event) - return onFormCreated(Schema.decodeUnknownSync(Form.Event.Created.data)(data).form).pipe(Effect.as(event)) - }), - }), + overrides?.bus ?? + Layer.mock(Bus.Service, { + subscribe: overrides?.subscribe ?? (() => Stream.never), + publish: (definition, data) => + Effect.suspend(() => { + const event = { + id: ID.create(), + type: definition.type, + data, + } as Payload + overrides?.published?.push(event.type) + if (event.type !== Form.Event.Created.type || !onFormCreated) return Effect.succeed(event) + return onFormCreated(Schema.decodeUnknownSync(Form.Event.Created.data)(data).form).pipe( + Effect.as(event), + ) + }), + }), Layer.mock(Integration.Service, { revision: () => 0, transform: () => Effect.succeed({ dispose: Effect.void }), @@ -417,7 +452,7 @@ function resourceMcpLayer( cancel: unusedIntegration, }, }), - Layer.mock(Credential.Service, { list: () => Effect.succeed([]) }), + Layer.mock(Credential.Service, { list: () => Effect.succeed([]), ...overrides?.credentials }), overrides?.environment ?? hostEnvironmentLayer, ), ), @@ -425,7 +460,7 @@ function resourceMcpLayer( } const connect = (server: string, config: typeof ConfigMCP.Server.Type, directory: string) => - McpClient.connect(server, config, directory).pipe(Effect.provide(hostEnvironmentLayer)) + McpClient.connect({ server, config, directory }).pipe(Effect.provide(hostEnvironmentLayer)) // Reads no longer wait for startup, so tests that assert on a connected server settle it first. const settled = (service: Mcp.Interface, name = "resources") => @@ -808,7 +843,7 @@ test("spawns local MCP servers through the location environment", async () => { await Effect.runPromise( Effect.scoped( Effect.gen(function* () { - const connection = yield* McpClient.connect("environment", config, import.meta.dir) + const connection = yield* McpClient.connect({ server: "environment", config, directory: import.meta.dir }) yield* connection.tools() }), ).pipe(Effect.provide(recordingEnvironmentLayer(spawns))), @@ -2239,6 +2274,7 @@ const shutdownIt = testEffect( Form.node, Environment.node, Location.node, + McpPool.node, ]), [ Location.node.replace( @@ -3196,3 +3232,676 @@ for (const source of ["config", "organization"] as const) { }), ) } + +describe("MCP pool", () => { + const live = testEffect(Layer.empty).live + const pooled = (url: string, fields: Partial = {}) => + new ConfigMCP.Remote({ type: "remote", url, oauth: false, pool: true, ...fields }) + const makePool = Layer.build(poolLayer).pipe(Effect.map((context) => Context.get(context, McpPool.Service))) + const directories = [import.meta.dir, path.join(import.meta.dir, "fixture")] + + const status = (mcp: Mcp.Interface) => mcp.servers().pipe(Effect.map((servers) => servers[0]?.status)) + + // Collects the pool's "not shared" messages with their details. + const poolLogs = () => { + const logs: Array = [] + const logger = Logger.map(Logger.formatStructured, (entry) => { + if (Array.isArray(entry.message) && String(entry.message[0]).startsWith("mcp pool ignored")) + logs.push([entry.message[0], entry.message[1]]) + }) + return { logs, layer: Logger.layer([logger]) } + } + + // A pool whose own spawns, the attempts at a shared local connection, are recorded. + const recordingPool = (spawns: Array) => + Layer.build( + McpPool.layer.pipe( + Layer.provide( + Layer.effect( + ChildProcessSpawner.ChildProcessSpawner, + Effect.gen(function* () { + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner + return ChildProcessSpawner.make((command) => { + spawns.push(command) + return spawner.spawn(command) + }) + }), + ).pipe(Layer.provide(LayerNode.compile(CrossSpawnSpawner.node))), + ), + ), + ).pipe(Effect.map((context) => Context.get(context, McpPool.Service))) + + // One Location's MCP service on the given pool; `shutdown` closes the Location as eviction would. + const open = ( + config: typeof ConfigMCP.Server.Type, + pool: McpPool.Interface, + directory: string, + overrides: { + onFormCreated?: (form: Form.Info) => Effect.Effect + published?: string[] + environment?: Layer.Layer + name?: string + credentials?: Partial + bus?: Layer.Layer + } = {}, + ) => + Effect.gen(function* () { + const scope = yield* Scope.make() + yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void)) + const context = yield* Layer.buildWithScope( + resourceMcpLayer(config, overrides.onFormCreated, undefined, { + pool: Layer.succeed(McpPool.Service, pool), + directory, + published: overrides.published, + environment: overrides.environment, + name: overrides.name, + credentials: overrides.credentials, + bus: overrides.bus, + }), + scope, + ) + const mcp = Context.get(context, Mcp.Service) + // Up to 10 seconds: a server that is down is retried for a while before it shows failed. + yield* status(mcp).pipe( + Effect.filterOrFail((status) => status?.status !== "pending"), + Effect.retry({ times: 1_000, schedule: Schedule.spaced("10 millis") }), + ) + return { mcp, forms: Context.get(context, Form.Service), shutdown: Scope.close(scope, Exit.void) } + }) + + live("shares one connection and one tool list between Locations", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false }) + const pool = yield* makePool + const a = yield* open(pooled(server.url), pool, directories[0]) + const b = yield* open(pooled(server.url), pool, directories[1]) + + const [toolsA, toolsB] = [yield* a.mcp.tools(), yield* b.mcp.tools()] + expect(toolsA.map((tool) => tool.name)).toEqual(["echo"]) + expect(toolsB.map((tool) => tool.name)).toEqual(["echo"]) + // Each Location tags its own copy of the one listed tool. + expect(toolsA[0]?.inputSchema).toBe(toolsB[0]?.inputSchema) + expect(server.state.toolLists).toBe(1) + yield* a.mcp.callTool({ server: "resources", name: "echo" }) + yield* b.mcp.callTool({ server: "resources", name: "echo" }) + expect(server.state.toolCalls).toHaveLength(2) + }), + ) + + live("keeps connections apart when the configs differ", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false }) + const pool = yield* makePool + const a = yield* open(pooled(server.url), pool, directories[0]) + const b = yield* open(pooled(server.url, { headers: { "x-account": "b" } }), pool, directories[0]) + expect((yield* a.mcp.tools())[0]?.inputSchema).not.toBe((yield* b.mcp.tools())[0]?.inputSchema) + expect(server.state.toolLists).toBe(2) + }), + ) + + test("keys connections on everything that changes them, and on no secret or name", () => { + const remote = new ConfigMCP.Remote({ + type: "remote", + url: "https://mcp.example.com", + headers: { authorization: "secret" }, + }) + const local = new ConfigMCP.Local({ type: "local", command: ["server"], environment: { TOKEN: "secret" } }) + const key = (input: Partial[0]> = {}) => McpPool.key({ config: remote, ...input }) + const localKey = (input: Partial[0]> = {}) => + McpPool.key({ config: local, cwd: "/a", ...input }) + + expect(key()).not.toContain("secret") + expect(localKey()).not.toContain("secret") + expect(key({ credential: "cred_a" })).not.toBe(key({ credential: "cred_b" })) + expect(key({ config: new ConfigMCP.Remote({ ...remote, headers: { authorization: "other" } }) })).not.toBe(key()) + expect(key({ config: new ConfigMCP.Remote({ ...remote, codemode: false }) })).not.toBe(key()) + expect(key({ config: new ConfigMCP.Remote({ ...remote, disabled: false }) })).toBe(key()) + expect(localKey()).not.toBe(localKey({ cwd: "/b" })) + expect(localKey({ config: new ConfigMCP.Local({ ...local, environment: { TOKEN: "other" } }) })).not.toBe( + localKey(), + ) + expect(localKey({ clientInfo: { name: "other", version: "1" } })).not.toBe(localKey()) + }) + + live("keeps a server that negotiates legacy private to each Location", () => { + const captured = poolLogs() + return Effect.gen(function* () { + const probes: Array = [] + const spawns: Array = [] + const pool = yield* recordingPool(probes) + const config = new ConfigMCP.Local({ + type: "local", + command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")], + cwd: directories[0], + pool: true, + }) + const a = yield* open(config, pool, directories[0], { environment: recordingEnvironmentLayer(spawns) }) + const b = yield* open(config, pool, directories[0], { environment: recordingEnvironmentLayer(spawns) }) + expect(yield* status(a.mcp)).toEqual({ status: "connected" }) + expect(yield* status(b.mcp)).toEqual({ status: "connected" }) + // One discovery attempt through the pool, then each Location spawns its own, as it would unpooled. + expect(probes).toHaveLength(1) + expect(spawns).toHaveLength(2) + // Once, when the verdict is recorded; the second Location skips straight to its own connection. + expect(captured.logs).toEqual([ + ["mcp pool ignored: server speaks an older protocol", { server: "resources", version: "2025-11-25" }], + ]) + }).pipe(Effect.provide(captured.layer)) + }) + + live("connects on its own when a server refuses the pooled handshake", () => { + const captured = poolLogs() + return Effect.gen(function* () { + const probes: Array = [] + const spawns: Array = [] + const pool = yield* recordingPool(probes) + // Exits during initialize unless the client declares roots, which shared connections never do. + const config = new ConfigMCP.Local({ + type: "local", + command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")], + cwd: directories[0], + environment: { MCP_REQUIRE_ROOTS: "1" }, + pool: true, + }) + const a = yield* open(config, pool, directories[0], { environment: recordingEnvironmentLayer(spawns) }) + expect(yield* status(a.mcp)).toEqual({ status: "connected" }) + const b = yield* open(config, pool, directories[0], { environment: recordingEnvironmentLayer(spawns) }) + expect(yield* status(b.mcp)).toEqual({ status: "connected" }) + expect(probes).toHaveLength(1) + expect(spawns).toHaveLength(2) + expect(captured.logs).toEqual([ + [ + "mcp pool ignored: server refused the shared connection", + { server: "resources", error: expect.stringContaining("Connection closed") }, + ], + ]) + }).pipe(Effect.provide(captured.layer)) + }) + + // A server that is down, or that refuses this client, would refuse a private connection too. + for (const [code, what, attempts] of [ + [503, "was down", 3], + [401, "rejected the credentials", 1], + [403, "refused access", 1], + ] as const) + live(`keeps pooling a server that ${what} when first tried`, () => { + const captured = poolLogs() + return Effect.gen(function* () { + const refusing = { value: true, count: 0 } + const server = yield* resourceServer({ + modern: true, + resources: false, + respond: () => { + if (!refusing.value) return undefined + refusing.count += 1 + return new Response(null, { status: code }) + }, + }) + const pool = yield* makePool + const a = yield* open(pooled(server.url), pool, directories[0]) + expect((yield* status(a.mcp))?.status).toBe("failed") + // The startup retries transient failures, and nothing tries a private connection afterwards. + expect(refusing.count).toBe(attempts) + expect(captured.logs).toEqual([]) + refusing.value = false + yield* a.mcp.connect("resources") + yield* open(pooled(server.url), pool, directories[1]) + expect(server.state.toolLists).toBe(1) + }).pipe(Effect.provide(captured.layer)) + }) + + live("decides a legacy server is private right after the handshake, before listing its tools", () => { + const captured = poolLogs() + return Effect.gen(function* () { + const tmp = yield* tmpdirScoped() + const wire = path.join(tmp.path, "wire") + // Connects without roots but needs one to list its tools, which shared connections never declare. + const config = new ConfigMCP.Local({ + type: "local", + command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")], + cwd: directories[0], + environment: { MCP_REQUIRE_ROOTS_TO_LIST: "1", MCP_WIRE_LOG: wire }, + pool: true, + }) + const pool = yield* makePool + const a = yield* open(config, pool, directories[0]) + const b = yield* open(config, pool, directories[1]) + expect(yield* status(a.mcp)).toEqual({ status: "connected" }) + expect(yield* status(b.mcp)).toEqual({ status: "connected" }) + const methods = (yield* Effect.promise(() => fs.readFile(wire, "utf8"))).trim().split("\n") + const count = (method: string) => methods.filter((item) => item === method).length + // The shared attempt probes, falls back to initialize, then closes without listing. The private + // connections know the server is legacy, so they skip the probe; each lists its two pages. + expect(count("server/discover")).toBe(1) + expect(count("initialize")).toBe(3) + expect(count("tools/list")).toBe(4) + expect(captured.logs).toEqual([ + ["mcp pool ignored: server speaks an older protocol", { server: "resources", version: expect.any(String) }], + ]) + }).pipe(Effect.provide(captured.layer)) + }) + + live("fails a pooled server that can't be spawned after one attempt", () => + Effect.gen(function* () { + const probes: Array = [] + const spawns: Array = [] + const pool = yield* recordingPool(probes) + const config = new ConfigMCP.Local({ type: "local", command: ["opencode-missing-mcp-server"], pool: true }) + const a = yield* open(config, pool, directories[0], { environment: recordingEnvironmentLayer(spawns) }) + expect((yield* status(a.mcp))?.status).toBe("failed") + expect(probes).toHaveLength(1) + // On Windows the spawn succeeds through the shell and the missing command shows up only as an exit + // during the handshake, which can't be told apart from a server refusing it, so it tries once more. + expect(spawns).toHaveLength(process.platform === "win32" ? 1 : 0) + }), + ) + + live("connects each Location on its own without pool", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false }) + const pool = yield* makePool + const config = new ConfigMCP.Remote({ type: "remote", url: server.url, oauth: false, protocol: "2026-07-28" }) + const a = yield* open(config, pool, directories[0]) + const b = yield* open(config, pool, directories[0]) + expect((yield* a.mcp.tools())[0]?.inputSchema).not.toBe((yield* b.mcp.tools())[0]?.inputSchema) + expect(server.state.toolLists).toBe(2) + }), + ) + + live("closes the shared connection when its last Location lets go", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false }) + const pool = yield* makePool + const a = yield* open(pooled(server.url), pool, directories[0]) + const b = yield* open(pooled(server.url), pool, directories[1]) + yield* a.shutdown + yield* b.mcp.callTool({ server: "resources", name: "echo" }) + const c = yield* open(pooled(server.url), pool, directories[0]) + expect(server.state.toolLists).toBe(1) + + yield* b.shutdown + yield* c.mcp.disconnect("resources") + yield* open(pooled(server.url), pool, directories[0]) + expect(server.state.toolLists).toBe(2) + }), + ) + + live("connects with the credential its key was made from, even when a sign-in lands mid-start", () => + Effect.gen(function* () { + // The authorization header of every tool call, in order. + const calls: Array = [] + const server = yield* resourceServer({ + modern: true, + resources: false, + respond: async (request) => { + if (request.method !== "POST") return undefined + const body: unknown = await request.clone().json() + if (isRecord(body) && body.method === "tools/call") calls.push(request.headers.get("authorization")) + return undefined + }, + }) + const pool = yield* makePool + // "resources" signs in right after its first read of the credential store; "guest" never signs in. + let signed: Integration.ID | undefined + let reads = 0 + const row = (integrationID: Integration.ID) => + new Credential.Info({ + id: Credential.ID.make("cred_signed"), + integrationID, + label: "signed", + value: { + type: "oauth", + methodID: Integration.MethodID.make("signed"), + access: "signed-in", + refresh: "signed-refresh", + expires: Date.now() + 3_600_000, + metadata: { serverUrl: server.url, tokenType: "Bearer" }, + }, + }) + const credentials: Partial = { + list: (integrationID) => + Effect.sync(() => { + signed ??= integrationID + if (integrationID !== signed) return [] + reads += 1 + return reads > 1 ? [row(integrationID)] : [] + }), + get: () => Effect.sync(() => (signed ? row(signed) : undefined)), + } + const config = pooled(server.url, { oauth: undefined }) + const owner = yield* open(config, pool, directories[0], { credentials }) + const guest = yield* open(config, pool, directories[1], { credentials, name: "guest" }) + yield* guest.mcp.callTool({ server: "guest", name: "echo" }) + // Reconnecting picks up the sign-in under a key of its own. + yield* owner.mcp.connect("resources") + yield* owner.mcp.callTool({ server: "resources", name: "echo" }) + yield* guest.mcp.callTool({ server: "guest", name: "echo" }) + expect(calls).toEqual([null, "Bearer signed-in", null]) + }), + ) + + for (const shared of [true, false]) + live( + `registers a server's prompt commands again after reconnecting${shared ? " to a connection another Location holds" : ""}`, + () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false }) + const config = shared + ? pooled(server.url) + : new ConfigMCP.Remote({ type: "remote", url: server.url, oauth: false, protocol: "2026-07-28" }) + const pool = yield* makePool + yield* open(config, pool, directories[0]) + // The second Location gets a working bus, so the command plugin hears its MCP events. + const hub = yield* PubSub.unbounded<{ readonly type: string }>() + const bus = Layer.mock(Bus.Service, { + publish: (definition, data) => + Effect.suspend(() => { + const event = { id: ID.create(), type: definition.type, data } as Payload + return PubSub.publish(hub, event).pipe(Effect.as(event)) + }), + subscribe: ((definition?: { readonly type: string }) => + Stream.fromPubSub(hub).pipe( + Stream.filter((event) => !definition || event.type === definition.type), + )) as Bus.Interface["subscribe"], + }) + const b = yield* open(config, pool, directories[1], { bus }) + const command = Context.get(yield* Layer.build(Command.layer.pipe(Layer.provide(bus))), Command.Service) + yield* CommandPlugin.Plugin.effect( + host({ + command: { + list: () => Effect.die("unused command.list"), + transform: command.transform, + reload: command.reload, + }, + }), + ).pipe( + Effect.provideService(Mcp.Service, b.mcp), + Effect.provide(bus), + Effect.provideService( + Location.Service, + Location.Service.of(location({ directory: AbsolutePath.make(directories[1]) })), + ), + ) + const registered = (expected: boolean) => + command.get("resources:greet").pipe( + Effect.filterOrFail((found) => (found !== undefined) === expected), + Effect.retry({ times: 200, schedule: Schedule.spaced("10 millis") }), + ) + yield* registered(true) + yield* b.mcp.disconnect("resources") + yield* registered(false) + yield* b.mcp.connect("resources") + expect(yield* status(b.mcp)).toEqual({ status: "connected" }) + yield* registered(true) + // A shared reconnect joins the open connection instead of listing again. + expect(server.state.toolLists).toBe(shared ? 1 : 3) + }), + ) + + live("routes an elicitation to the Location whose call caused it", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false, urlElicitation: true }) + const pool = yield* makePool + const created = yield* Deferred.make() + const elsewhere: Form.Info[] = [] + const a = yield* open(pooled(server.url), pool, directories[0], { + onFormCreated: (form) => Effect.sync(() => elsewhere.push(form)), + }) + const b = yield* open(pooled(server.url), pool, directories[1], { + onFormCreated: (form) => recordForm(created, form), + }) + const call = yield* b.mcp.callTool({ server: "resources", name: "url-elicitation" }).pipe(Effect.forkScoped) + const { form, directory } = yield* Deferred.await(created) + expect(directory).toBe(directories[1]) + yield* b.forms.reply({ id: form.id, answer: { elicitation: true } }) + expect((yield* Fiber.join(call)).structured).toEqual({ action: "accept" }) + expect(elsewhere).toEqual([]) + expect(yield* a.forms.list()).toEqual([]) + }), + ) + + live("asks every holder about an elicitation no request claims, and takes the first answer", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false, urlElicitation: true }) + const pool = yield* makePool + const environment = Context.get(yield* Layer.build(hostEnvironmentLayer), Environment.Service) + const config = new ConfigMCP.Remote({ type: "remote", url: server.url, oauth: false, protocol: "2026-07-28" }) + // Each holder knows the server by its own name; the connection carries the first one's. + const holder = (directory: string, name: string) => + Effect.gen(function* () { + const asked: string[] = [] + const forms = Context.get( + yield* Layer.build( + Form.layer.pipe( + Layer.provide( + Layer.mock(Bus.Service, { + publish: (definition, data) => + Effect.succeed({ id: ID.create(), type: definition.type, data } as Payload), + }), + ), + ), + ), + Form.Service, + ) + const scope = yield* Effect.scope + const run = yield* FiberSet.makeRuntime() + const connection = pool.connection({ + name, + config, + directory, + authProvider: Effect.undefined, + elicitation: { + create: (request) => + Effect.sync(() => asked.push(request.server)).pipe( + Effect.andThen( + forms.ask({ sessionID: "global", title: "Confirm", fields: [{ key: "ok", type: "boolean" }] }), + ), + Effect.map((state) => ({ action: state.status === "answered" ? "accept" : "cancel" }) as const), + ), + complete: () => Effect.void, + }, + environment, + fetch, + scope, + lock: Semaphore.makeUnsafe(1).withPermit, + callbacks: run, + fork: run, + events: { + connecting: Effect.void, + connected: Effect.void, + failed: () => Effect.void, + settled: Effect.void, + closed: () => Effect.void, + changed: () => Effect.void, + }, + select: Effect.succeed({ key: McpPool.key({ config }), authProvider: Effect.undefined }), + }) + yield* connection.start + return { connection, forms, asked } + }) + const a = yield* holder(directories[0], "first") + const b = yield* holder(directories[1], "second") + const client = a.connection.client + if (!client) throw new Error("expected a shared connection") + expect(b.connection.client).toBe(client) + + // Called on the shared client directly, so no Location claims the request. + const call = yield* client.callTool({ name: "url-elicitation" }).pipe(Effect.forkScoped) + const pending = (forms: Form.Interface) => + forms.list().pipe( + Effect.flatMap((list) => (list[0] ? Effect.succeed(list[0]) : Effect.fail("none"))), + Effect.retry({ times: 200, schedule: Schedule.spaced("10 millis") }), + ) + const asked = yield* pending(a.forms) + const other = yield* pending(b.forms) + yield* a.forms.reply({ id: asked.id, answer: { ok: true } }) + expect((yield* Fiber.join(call)).structured).toEqual({ action: "accept" }) + expect((yield* b.forms.state(other.id)).status).toBe("cancelled") + expect([a.asked, b.asked]).toEqual([["first"], ["second"]]) + }), + ) + + live("fans tool list changes out to every Location", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false, listChanged: true }) + const pool = yield* makePool + const published = [[], []] as string[][] + const a = yield* open(pooled(server.url), pool, directories[0], { published: published[0] }) + const b = yield* open(pooled(server.url), pool, directories[1], { published: published[1] }) + published.forEach((events) => events.splice(0)) + server.state.extraTools = [{ name: "added", inputSchema: { type: "object", properties: {} } }] + yield* Effect.promise(server.sendToolListChanged) + for (const mcp of [a.mcp, b.mcp]) + yield* mcp.tools().pipe( + Effect.filterOrFail((tools) => tools.some((tool) => tool.name === "added")), + Effect.retry({ times: 200, schedule: Schedule.spaced("10 millis") }), + ) + expect(server.state.toolLists).toBe(2) + for (const events of published) + yield* Effect.sync(() => events).pipe( + Effect.filterOrFail((events) => events.includes(McpEvent.ToolsChanged.type)), + Effect.retry({ times: 200, schedule: Schedule.spaced("10 millis") }), + ) + }), + ) + + live("answers no roots on a shared connection", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false, roots: true }) + const pool = yield* makePool + const own = yield* open( + new ConfigMCP.Remote({ type: "remote", url: server.url, oauth: false, protocol: "2026-07-28" }), + pool, + directories[0], + ) + expect((yield* own.mcp.callTool({ server: "resources", name: "roots" })).structured).toEqual({ + kind: "roots", + roots: [{ uri: Bun.pathToFileURL(directories[0]).href }], + }) + const shared = yield* open(pooled(server.url), pool, directories[0]) + const error = yield* shared.mcp.callTool({ server: "resources", name: "roots" }).pipe(Effect.flip) + expect(error.message).toContain("roots/list") + }), + ) + + live("shares a local server across directories only when its cwd is fixed", () => { + const captured = poolLogs() + return Effect.gen(function* () { + const tmp = yield* tmpdirScoped() + const server = (pids: string, cwd?: string) => + new ConfigMCP.Local({ + type: "local", + command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-modern-stdio.ts")], + environment: { MCP_PID_FILE: path.join(tmp.path, pids) }, + cwd, + pool: true, + }) + const started = (pids: string) => + Effect.promise(() => fs.readFile(path.join(tmp.path, pids), "utf8")).pipe( + Effect.map((text) => text.trim().split("\n")), + ) + const pool = yield* makePool + for (const directory of directories) yield* open(server("home", "~"), pool, directory) + expect(yield* started("home")).toHaveLength(1) + expect(captured.logs).toEqual([]) + + for (const directory of directories) yield* open(server("project"), pool, directory) + expect(yield* started("project")).toHaveLength(2) + expect(captured.logs).toEqual([ + ["mcp pool ignored: local server has no fixed cwd, so each directory runs its own", { server: "resources" }], + ]) + }).pipe(Effect.provide(captured.layer)) + }) + + live("shares one local process, fails every holder when it dies, and closes it after the last", () => + Effect.gen(function* () { + const tmp = yield* tmpdirScoped() + const pids = path.join(tmp.path, "pids") + const config = new ConfigMCP.Local({ + type: "local", + command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-modern-stdio.ts")], + environment: { MCP_PID_FILE: pids }, + pool: true, + }) + const started = () => + Effect.promise(() => fs.readFile(pids, "utf8")).pipe(Effect.map((text) => text.trim().split("\n").map(Number))) + const alive = (pid: number) => { + try { + process.kill(pid, 0) + return true + } catch { + return false + } + } + const until = (effect: Effect.Effect, check: (value: A) => boolean) => + effect.pipe( + Effect.filterOrFail(check, () => "pending"), + Effect.retry({ times: 500, schedule: Schedule.spaced("10 millis") }), + ) + const pool = yield* makePool + const a = yield* open(config, pool, directories[0]) + const b = yield* open(config, pool, directories[0]) + const [first] = yield* started() + expect(yield* started()).toHaveLength(1) + expect((yield* a.mcp.tools())[0]?.inputSchema).toBe((yield* b.mcp.tools())[0]?.inputSchema) + + process.kill(first!, "SIGKILL") + for (const location of [a, b]) yield* until(status(location.mcp), (status) => status?.status === "failed") + yield* a.mcp.connect("resources") + expect(yield* status(a.mcp)).toEqual({ status: "connected" }) + expect((yield* status(b.mcp))?.status).toBe("failed") + yield* b.mcp.connect("resources") + expect(yield* status(b.mcp)).toEqual({ status: "connected" }) + const [, second] = yield* started() + expect(yield* started()).toHaveLength(2) + + yield* a.shutdown + expect(alive(second!)).toBe(true) + yield* b.mcp.callTool({ server: "resources", name: "echo" }) + yield* b.shutdown + yield* until( + Effect.sync(() => alive(second!)), + (alive) => !alive, + ) + }), + ) + + live("keeps nothing of a Location that let go of a shared connection", () => + Effect.gen(function* () { + const server = yield* resourceServer({ modern: true, resources: false, urlElicitation: true }) + const pool = yield* makePool + // Reading a WeakRef keeps its target alive until the current job ends, so watch for finalization instead. + const collected = new Set() + const registry = new FinalizationRegistry((name) => collected.add(name)) + // The first Location opens the connection and makes a call through it, then lets go while another holds on. + const shutdown = yield* Effect.gen(function* () { + const created = yield* Deferred.make() + const location = yield* open(pooled(server.url), pool, directories[0], { + onFormCreated: (form) => recordForm(created, form), + }) + const call = yield* location.mcp + .callTool({ server: "resources", name: "url-elicitation" }) + .pipe(Effect.forkScoped) + const { form } = yield* Deferred.await(created) + yield* location.forms.reply({ id: form.id, answer: { elicitation: true } }) + yield* Fiber.join(call) + registry.register(location.mcp, "mcp") + registry.register(location.forms, "forms") + return location.shutdown + }) + const second = yield* open(pooled(server.url), pool, directories[1]) + yield* shutdown + // The collector also scans the native stack, where a stale pointer from the shutdown can survive in + // frames the event loop reuses. Unrelated work through the same paths overwrites those; then collect. + for (let attempt = 0; attempt < 50 && collected.size < 2; attempt++) { + yield* Effect.forEach(Array.from({ length: 20 }), () => Effect.promise(() => Bun.sleep(0)), { + concurrency: "unbounded", + }) + yield* Effect.promise(() => new Promise((resolve) => setTimeout(() => resolve(Bun.gc(true)), 0))) + } + expect(Array.from(collected).toSorted()).toEqual(["forms", "mcp"]) + expect(yield* status(second.mcp)).toEqual({ status: "connected" }) + expect(server.state.toolLists).toBe(1) + }), + ) +}) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 5ed182b44ed..27e04d73e4f 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -20185,6 +20185,9 @@ }, "protocol": { "$ref": "#/components/schemas/Mcp.Protocol" + }, + "pool": { + "type": "boolean" } }, "required": ["type", "command"], @@ -20277,6 +20280,9 @@ }, "protocol": { "$ref": "#/components/schemas/Mcp.Protocol" + }, + "pool": { + "type": "boolean" } }, "required": ["type", "url"], diff --git a/packages/schema/src/mcp.ts b/packages/schema/src/mcp.ts index 2d782dd6a40..003bf930a83 100644 --- a/packages/schema/src/mcp.ts +++ b/packages/schema/src/mcp.ts @@ -36,6 +36,10 @@ export class LocalConfig extends Schema.Class("Mcp.LocalConfig")({ }), timeout: TimeoutConfig.pipe(optional), protocol: Protocol.pipe(optional), + pool: Schema.Boolean.pipe(optional).annotate({ + description: + 'Share one connection to this server across every directory that configures it identically, instead of one per directory. Only connections that negotiate the 2026-07-28 revision are shared; an unset "protocol" becomes "auto", and "legacy" never shares. Defaults to false.', + }), }) {} export class OAuthConfig extends Schema.Class("Mcp.OAuthConfig")({ @@ -61,6 +65,10 @@ export class RemoteConfig extends Schema.Class("Mcp.RemoteConfig") }), timeout: TimeoutConfig.pipe(optional), protocol: Protocol.pipe(optional), + pool: Schema.Boolean.pipe(optional).annotate({ + description: + 'Share one connection to this server across every directory that configures it identically, instead of one per directory. Only connections that negotiate the 2026-07-28 revision are shared; an unset "protocol" becomes "auto", and "legacy" never shares. Defaults to false.', + }), }) {} export const ServerConfig = Schema.Union([LocalConfig, RemoteConfig]).pipe(Schema.toTaggedUnion("type")) diff --git a/patches/@modelcontextprotocol%2Fclient@2.3.1.patch b/patches/@modelcontextprotocol%2Fclient@2.3.1.patch index b8291f818c6..649df885913 100644 --- a/patches/@modelcontextprotocol%2Fclient@2.3.1.patch +++ b/patches/@modelcontextprotocol%2Fclient@2.3.1.patch @@ -1,5 +1,5 @@ diff --git a/dist/index.cjs b/dist/index.cjs -index 71cf63076b073284aa14f63cd41efa653e8def0f..d4679fc706c76b87949fd674857cea54793e82ce 100644 +index 71cf63076b073284aa14f63cd41efa653e8def0f..90e2a8778c4a0981aa57d3b5c6657d9c7c0e3562 100644 --- a/dist/index.cjs +++ b/dist/index.cjs @@ -1038,7 +1038,6 @@ async function discoverMetadataWithFallback(serverUrl, wellKnownType, fetchFn, o @@ -18,7 +18,25 @@ index 71cf63076b073284aa14f63cd41efa653e8def0f..d4679fc706c76b87949fd674857cea54 if (resource) authorizationUrl.searchParams.set("resource", resourceIndicatorToString(resource)); return { authorizationUrl, -@@ -4350,7 +4348,7 @@ var Client = class extends require_src.Protocol { +@@ -3206,7 +3204,16 @@ var Client = class extends require_src.Protocol { + })); + return require_src.runInputRequiredFlow({ + getRequestHandler: (method) => this._getRequestHandler(method), +- buildContext: (baseCtx) => this.buildContext(baseCtx, void 0), ++ buildContext: (baseCtx) => this.buildContext({ ++ ...baseCtx, ++ mcpReq: { ++ ...baseCtx.mcpReq, ++ origin: { ++ request: flow.request, ++ options: flow.options ++ } ++ } ++ }, void 0), + sessionId: this.transport?.sessionId + }, this._inputRequiredDriverConfig, decoded, flow); + } +@@ -4350,7 +4357,7 @@ var Client = class extends require_src.Protocol { _excludeInvalidXMcpHeaderTools(result) { if (this.getProtocolEra() !== "modern" || !this.transport || detectProbeTransportKind(this.transport) === "stdio") return; const filtered = result.tools.filter((tool) => { @@ -28,7 +46,7 @@ index 71cf63076b073284aa14f63cd41efa653e8def0f..d4679fc706c76b87949fd674857cea54 console.warn(`[mcp-sdk] excluding tool '${tool.name}' from tools/list: invalid x-mcp-header declaration — ${scan.reason}`); return false; diff --git a/dist/index.mjs b/dist/index.mjs -index c1a09a82b8121d6a1b038ccc6d02bae46d55dbcf..bf457bdfdef05ad8d09f3fbb94c6ac1aecc59487 100644 +index c1a09a82b8121d6a1b038ccc6d02bae46d55dbcf..0adaa1f8ef80f1bd29581e896add283258a57918 100644 --- a/dist/index.mjs +++ b/dist/index.mjs @@ -1035,7 +1035,6 @@ async function discoverMetadataWithFallback(serverUrl, wellKnownType, fetchFn, o @@ -47,7 +65,25 @@ index c1a09a82b8121d6a1b038ccc6d02bae46d55dbcf..bf457bdfdef05ad8d09f3fbb94c6ac1a if (resource) authorizationUrl.searchParams.set("resource", resourceIndicatorToString(resource)); return { authorizationUrl, -@@ -4347,7 +4345,7 @@ var Client = class extends Protocol { +@@ -3203,7 +3201,16 @@ var Client = class extends Protocol { + })); + return runInputRequiredFlow({ + getRequestHandler: (method) => this._getRequestHandler(method), +- buildContext: (baseCtx) => this.buildContext(baseCtx, void 0), ++ buildContext: (baseCtx) => this.buildContext({ ++ ...baseCtx, ++ mcpReq: { ++ ...baseCtx.mcpReq, ++ origin: { ++ request: flow.request, ++ options: flow.options ++ } ++ } ++ }, void 0), + sessionId: this.transport?.sessionId + }, this._inputRequiredDriverConfig, decoded, flow); + } +@@ -4347,7 +4354,7 @@ var Client = class extends Protocol { _excludeInvalidXMcpHeaderTools(result) { if (this.getProtocolEra() !== "modern" || !this.transport || detectProbeTransportKind(this.transport) === "stdio") return; const filtered = result.tools.filter((tool) => { diff --git a/services/www/src/docs/content/mcp-servers.mdx b/services/www/src/docs/content/mcp-servers.mdx index 5f3405214e6..241fcf3a3b6 100644 --- a/services/www/src/docs/content/mcp-servers.mdx +++ b/services/www/src/docs/content/mcp-servers.mdx @@ -119,6 +119,7 @@ Use configuration for other process options such as a working directory: | `codemode` | No | Set to `false` to expose tools directly instead of through Code Mode. Defaults to `true`. | | `timeout` | No | Per-server timeout overrides. | | `protocol` | No | `legacy` (default), `auto`, or `2026-07-28`. See [Protocol version](#protocol-version). | +| `pool` | No | Share one connection across directories. Defaults to `false`. See [Shared connections](#shared-connections). | Use `{env:NAME}` for environment substitution. Shell expressions such as `$NAME` are not expanded in JSON strings: @@ -174,6 +175,7 @@ Use configuration for other options. Store secrets in environment variables rath | `codemode` | No | Set to `false` to expose tools directly instead of through Code Mode. Defaults to `true`. | | `timeout` | No | Per-server timeout overrides. | | `protocol` | No | `legacy` (default), `auto`, or `2026-07-28`. See [Protocol version](#protocol-version). | +| `pool` | No | Share one connection across directories. Defaults to `false`. See [Shared connections](#shared-connections). | Use `oauth: false` only when the server exclusively uses an API key or another header credential: @@ -357,6 +359,31 @@ OpenCode opens every server with the classic MCP `initialize` handshake by defau Probing a local `legacy` server adds a short-lived extra process and can wait up to the startup timeout when the server ignores unknown requests, so keep `auto` scoped to servers that need it. +## Shared connections + +One OpenCode server can have many directories open, and each one connects to every MCP server on its own. Set `pool` to `true` to let directories with the same server settings share one connection and one tool list: + +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "servers": { + "cloudflare": { + "type": "remote", + "url": "https://mcp.cloudflare.com/mcp", + "pool": true, + }, + }, + }, +} +``` + +- Only connections on the 2026-07-28 revision are shared. With `pool` set, an unset `protocol` means `auto`. A server that answers with an older revision, or one set to `legacy`, keeps one connection per directory. +- Directories share a connection only when everything that changes it matches: the URL, headers, OAuth settings and signed-in account for a remote server, and the command, working directory and environment for a local one. Timeouts and `protocol` must match too. The server's name doesn't need to, but sign-ins are stored per name, so an OAuth server is shared only under the same name. +- A local server is shared only between directories on this machine, not ones in a workspace. Sharing it across projects needs a fixed `cwd`, such as `"~"`. Without one it runs in each project's folder, so each project gets its own and OpenCode logs a warning. +- A shared connection has no roots. When a tool asks for input, the request appears in the directory that called it. +- The connection closes as soon as the last directory using it closes or disconnects the server. + ## Names OpenCode names a tool `_`. It replaces characters other than letters, numbers, `_`, and `-` with `_`: