feat(core): share MCP connections across locations with pool: true (#61185)

This commit is contained in:
Aiden Cline
2026-11-04 17:43:08 -06:00
committed by GitHub
Unverified
parent b551f60452
commit 33d52e6011
14 changed files with 1522 additions and 123 deletions
+4
View File
@@ -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
}
}
+92 -33
View File
@@ -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<NeedsAuthError>()("MCP.Ne
export class ConnectError extends Schema.TaggedError<ConnectError>()("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<void>
}
/** 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<Resource[], Error>
readonly resourceTemplates: () => Effect.Effect<ResourceTemplateType[], Error>
/** Resolves to undefined when the server does not advertise resources. */
readonly readResource: (input: { readonly uri: string }) => Effect.Effect<ReadResourceResult | undefined, Error>
readonly prompt: (input: {
readonly name: string
readonly args?: Record<string, string>
}) => Effect.Effect<GetPromptResult, Error>
readonly callTool: (input: {
readonly name: string
readonly args?: Record<string, unknown>
readonly sessionID?: Session.ID
}) => Effect.Effect<CallToolResult, Error>
readonly readResource: (
input: { readonly uri: string } & PerRequest,
) => Effect.Effect<ReadResourceResult | undefined, Error>
readonly prompt: (
input: {
readonly name: string
readonly args?: Record<string, string>
} & PerRequest,
) => Effect.Effect<GetPromptResult, Error>
readonly callTool: (
input: {
readonly name: string
readonly args?: Record<string, unknown>
readonly sessionID?: Session.ID
} & PerRequest,
) => Effect.Effect<CallToolResult, Error>
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<AbortSignal, ElicitationHandler["create"]>()
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) {
+56 -23
View File
@@ -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<Mcp.Status, { readonly status: "failed" | "needs_auth" }>
/** 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<string>()
/**
* 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<void>
/** The attempt connected and listed its tools. */
readonly connected: Effect.Effect<void>
readonly failed: (failure: Failure) => Effect.Effect<void>
/** `answered` is true when the server was reached but refused or broke the handshake. */
readonly failed: (failure: Failure, answered: boolean) => Effect.Effect<void>
/** The attempt ended, however it ended. */
readonly settled: Effect.Effect<void>
/** A live connection was torn down. */
readonly stopped: Effect.Effect<void>
/** The live connection closed on its own. Runs under the lock; the owner decides how to stop. */
readonly closed: (reason: string) => Effect.Effect<void>
readonly toolsChanged: Effect.Effect<void>
readonly promptsChanged: Effect.Effect<void>
readonly resourcesChanged: Effect.Effect<void>
/** A catalog changed: the server said so, or the connection was torn down and every catalog emptied. */
readonly changed: (kind: Kind) => Effect.Effect<void>
/**
* 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<void>
}
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<OAuthClientProvider | undefined>
@@ -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: <A, E>(effect: Effect.Effect<A, E>) => Effect.Effect<A, E>
/** Wraps the handshake and initial tool list. */
readonly handshake: <A, E>(effect: Effect.Effect<A, E>) => Effect.Effect<A, E>
/** Runs callbacks from the live connection. */
readonly callbacks: (effect: Effect.Effect<void>) => 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<void> = 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<McpClient.Tool> }, 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 {
+74 -29
View File
@@ -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<string>()
const changes = { tools: McpEvent.ToolsChanged, resources: McpEvent.ResourcesChanged, prompts: PromptsChanged }
type Data = {
servers: Map<ServerName, Types.DeepMutable<Mcp.ServerConfig>>
@@ -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<never, void, never>()
// 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,
],
})
}
+6 -2
View File
@@ -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
+377
View File
@@ -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<Selection>
}
export interface Selection {
readonly key: string
readonly authProvider: Effect.Effect<OAuthClientProvider | undefined>
}
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<Service, Interface>()("@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<string, string> | 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<OAuthClientProvider | undefined>
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<Holder>
readonly lock: Semaphore.Semaphore
readonly outcome: Deferred.Deferred<Outcome>
start?: Fiber.Fiber<void>
connected: boolean
}
export const layer = Layer.effect(
Service,
Effect.gen(function* () {
const scope = yield* Effect.scope
const run = yield* FiberSet.makeRuntime<never, void, never>()
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<string, Slot>()
// Keys whose server negotiated legacy or refused the pooled handshake. Kept for the life of the process.
const unpoolable = new Set<string>()
// 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<string>()
// Names of local servers already warned about for having no cwd, which keeps each project's folder in the key.
const unfixed = new Set<string>()
// Takes only data from the Location that opens it: the connection outlives that Location's claim.
const open = (key: string, input: Pick<Input, "name" | "config" | "directory" | "clientInfo">) => {
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<void>) =>
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] })
@@ -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
})
@@ -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)
}
}
+57 -5
View File
@@ -55,7 +55,9 @@ const memoryCredentials = (initial: Credential.Info[]) => {
const connectProvider = (config: typeof ConfigMCP.Remote.Type, store: ReturnType<typeof memoryCredentials>) =>
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)
+730 -21
View File
@@ -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<Response | undefined>
} = {},
) {
@@ -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<void>,
@@ -335,9 +360,15 @@ function resourceMcpLayer(
subscribe?: Bus.Interface["subscribe"]
environment?: Layer.Layer<Environment.Service>
published?: string[]
pool?: Layer.Layer<McpPool.Service>
directory?: string
/** The configured server's name; "resources" unless given. */
name?: string
credentials?: Partial<Credential.Interface>
bus?: Layer.Layer<Bus.Service>
},
) {
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<typeof definition>
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<typeof definition>
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<ConfigMCP.Remote> = {}) =>
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<readonly [string, unknown]> = []
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<ChildProcess.Command>) =>
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<void>
published?: string[]
environment?: Layer.Layer<Environment.Service>
name?: string
credentials?: Partial<Credential.Interface>
bus?: Layer.Layer<Bus.Service>
} = {},
) =>
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<Parameters<typeof McpPool.key>[0]> = {}) => McpPool.key({ config: remote, ...input })
const localKey = (input: Partial<Parameters<typeof McpPool.key>[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<ChildProcess.Command> = []
const spawns: Array<ChildProcess.Command> = []
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<ChildProcess.Command> = []
const spawns: Array<ChildProcess.Command> = []
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<ChildProcess.Command> = []
const spawns: Array<ChildProcess.Command> = []
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<string | null> = []
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<Credential.Interface> = {
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<typeof definition>
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<CreatedForm>()
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<typeof definition>),
}),
),
),
),
Form.Service,
)
const scope = yield* Effect.scope
const run = yield* FiberSet.makeRuntime<never, void, never>()
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 = <A>(effect: Effect.Effect<A>, 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<string>()
const registry = new FinalizationRegistry<string>((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<CreatedForm>()
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<void>((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)
}),
)
})
+6
View File
@@ -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"],
+8
View File
@@ -36,6 +36,10 @@ export class LocalConfig extends Schema.Class<LocalConfig>("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<OAuthConfig>("Mcp.OAuthConfig")({
@@ -61,6 +65,10 @@ export class RemoteConfig extends Schema.Class<RemoteConfig>("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"))
@@ -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) => {
@@ -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 `<server>_<tool>`. It replaces characters other than letters, numbers, `_`, and `-` with `_`: