@executor-js/plugin-mcp 0.0.1 → 0.1.0

package/dist/sdk/plugin.d.ts

@@ -1,18 +1,30 @@
 import { Effect } from "effect";
-import { type ExecutorPlugin } from "@executor-js/sdk";
-import { type McpConnectionAuth } from "./types";
+import { McpExtensionService } from "../api/handlers";
+import { type StorageFailure } from "@executor-js/sdk/core";
 import { type McpBindingStore, type McpStoredSource } from "./binding-store";
-export interface McpRemoteSourceConfig {
+import { McpConnectionError, McpToolDiscoveryError } from "./errors";
+import { type McpConnectionAuth, type SecretBackedValue } from "./types";
+import { type ConfigFileSink } from "@executor-js/config";
+/**
+ * Executor scope id that owns a newly-added MCP source row. Must be one
+ * of the executor's configured scopes. Admins adding a shared server at
+ * org scope pin here; per-user stdio sources can pin at the inner
+ * scope.
+ */
+type McpSourceScopeField = {
+    readonly scope: string;
+};
+export interface McpRemoteSourceConfig extends McpSourceScopeField {
     readonly transport: "remote";
     readonly name: string;
     readonly endpoint: string;
     readonly remoteTransport?: "streamable-http" | "sse" | "auto";
-    readonly queryParams?: Record<string, string>;
-    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, SecretBackedValue>;
+    readonly headers?: Record<string, SecretBackedValue>;
     readonly namespace?: string;
     readonly auth?: McpConnectionAuth;
 }
-export interface McpStdioSourceConfig {
+export interface McpStdioSourceConfig extends McpSourceScopeField {
     readonly transport: "stdio";
     readonly name: string;
     readonly command: string;
@@ -22,27 +34,6 @@ export interface McpStdioSourceConfig {
     readonly namespace?: string;
 }
 export type McpSourceConfig = McpRemoteSourceConfig | McpStdioSourceConfig;
-export interface McpOAuthStartInput {
-    readonly endpoint: string;
-    readonly redirectUrl: string;
-    readonly queryParams?: Record<string, string> | null;
-}
-export interface McpOAuthStartResponse {
-    readonly sessionId: string;
-    readonly authorizationUrl: string;
-}
-export interface McpOAuthCompleteInput {
-    readonly state: string;
-    readonly code?: string;
-    readonly error?: string;
-}
-export interface McpOAuthCompleteResponse {
-    readonly accessTokenSecretId: string;
-    readonly refreshTokenSecretId: string | null;
-    readonly tokenType: string;
-    readonly expiresAt: number | null;
-    readonly scope: string | null;
-}
 export interface McpProbeResult {
     readonly connected: boolean;
     readonly requiresOAuth: boolean;
@@ -54,27 +45,231 @@ export interface McpProbeResult {
 export interface McpUpdateSourceInput {
     readonly name?: string;
     readonly endpoint?: string;
-    readonly headers?: Record<string, string>;
-    readonly queryParams?: Record<string, string>;
+    readonly headers?: Record<string, SecretBackedValue>;
+    readonly queryParams?: Record<string, SecretBackedValue>;
     readonly auth?: McpConnectionAuth;
 }
+export interface McpProbeEndpointInput {
+    readonly endpoint: string;
+    readonly headers?: Record<string, SecretBackedValue>;
+    readonly queryParams?: Record<string, SecretBackedValue>;
+}
+export interface McpPluginOptions {
+    /**
+     * Allow configuring stdio-transport MCP sources. Off by default.
+     *
+     * Stdio sources spawn a local subprocess that inherits the parent
+     * `process.env`. Only enable for trusted single-user contexts.
+     */
+    readonly dangerouslyAllowStdioMCP?: boolean;
+    /** If provided, source add/remove is mirrored to executor.jsonc
+     *  (best-effort — file errors are logged, not raised). */
+    readonly configFile?: ConfigFileSink;
+}
+export declare const mcpPlugin: import("@executor-js/sdk/core").ConfiguredPlugin<"mcp", {
+    probeEndpoint: (input: string | McpProbeEndpointInput) => Effect.Effect<{
+        connected: true;
+        requiresOAuth: false;
+        name: string;
+        namespace: string;
+        toolCount: number;
+        serverName: string | null;
+    } | {
+        connected: false;
+        requiresOAuth: true;
+        name: string;
+        namespace: string;
+        toolCount: null;
+        serverName: null;
+    }, StorageFailure | McpConnectionError, never>;
+    addSource: (config: McpSourceConfig) => Effect.Effect<{
+        toolCount: number;
+        namespace: string;
+    }, StorageFailure | McpConnectionError | McpToolDiscoveryError, never>;
+    removeSource: (namespace: string, scope: string) => Effect.Effect<void, StorageFailure, never>;
+    refreshSource: (namespace: string, scope: string) => Effect.Effect<{
+        toolCount: number;
+    }, StorageFailure | McpConnectionError | McpToolDiscoveryError, never>;
+    getSource: (namespace: string, scope: string) => Effect.Effect<McpStoredSource | null, StorageFailure, never>;
+    updateSource: (namespace: string, scope: string, input: McpUpdateSourceInput) => Effect.Effect<void, StorageFailure, never>;
+}, McpBindingStore, McpPluginOptions, {
+    readonly mcp_source: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly config: {
+                readonly type: "json";
+                readonly required: true;
+            };
+            readonly created_at: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+    readonly mcp_binding: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly binding: {
+                readonly type: "json";
+                readonly required: true;
+            };
+            readonly created_at: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+}, typeof McpExtensionService, import("effect/Layer").Layer<import("effect/unstable/httpapi/HttpApiGroup").ApiGroup<"executor", "mcp">, never, import("effect/unstable/http/HttpRouter").Request<"Requires", McpExtensionService>>, import("effect/unstable/httpapi/HttpApiGroup").HttpApiGroup<"mcp", import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"probeEndpoint", "POST", "/scopes/:scopeId/mcp/probe", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly endpoint: import("effect/Schema").String;
+    readonly headers: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+    readonly queryParams: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly connected: import("effect/Schema").Boolean;
+    readonly requiresOAuth: import("effect/Schema").Boolean;
+    readonly name: import("effect/Schema").String;
+    readonly namespace: import("effect/Schema").String;
+    readonly toolCount: import("effect/Schema").NullOr<import("effect/Schema").Number>;
+    readonly serverName: import("effect/Schema").NullOr<import("effect/Schema").String>;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never> | import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"addSource", "POST", "/scopes/:scopeId/mcp/sources", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+    readonly transport: import("effect/Schema").Literal<"remote">;
+    readonly name: import("effect/Schema").String;
+    readonly endpoint: import("effect/Schema").String;
+    readonly remoteTransport: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["streamable-http", "sse", "auto"]>>;
+    readonly namespace: import("effect/Schema").optional<import("effect/Schema").String>;
+    readonly queryParams: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+    readonly headers: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+    readonly auth: import("effect/Schema").optional<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"none">;
+    }>, import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"header">;
+        readonly headerName: import("effect/Schema").String;
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>, import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"oauth2">;
+        readonly connectionId: import("effect/Schema").String;
+        readonly clientIdSecretId: import("effect/Schema").optional<import("effect/Schema").String>;
+        readonly clientSecretSecretId: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").String>>;
+    }>]>>;
+}>, import("effect/Schema").Struct<{
+    readonly transport: import("effect/Schema").Literal<"stdio">;
+    readonly name: import("effect/Schema").String;
+    readonly command: import("effect/Schema").String;
+    readonly args: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").String>>;
+    readonly env: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").String>>;
+    readonly cwd: import("effect/Schema").optional<import("effect/Schema").String>;
+    readonly namespace: import("effect/Schema").optional<import("effect/Schema").String>;
+}>]>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly toolCount: import("effect/Schema").Number;
+    readonly namespace: import("effect/Schema").String;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never> | import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"removeSource", "POST", "/scopes/:scopeId/mcp/sources/remove", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly namespace: import("effect/Schema").String;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly removed: import("effect/Schema").Boolean;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never> | import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"refreshSource", "POST", "/scopes/:scopeId/mcp/sources/refresh", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly namespace: import("effect/Schema").String;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly toolCount: import("effect/Schema").Number;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never> | import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"getSource", "GET", "/scopes/:scopeId/mcp/sources/:namespace", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+    namespace: import("effect/Schema").String;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").NullOr<typeof import("./stored-source").McpStoredSourceSchema>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never> | import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"updateSource", "PATCH", "/scopes/:scopeId/mcp/sources/:namespace", import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<import("effect/Schema").Struct<{
+    scopeId: import("effect/Schema").brand<import("effect/Schema").String, "ScopeId">;
+    namespace: import("effect/Schema").String;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+    readonly endpoint: import("effect/Schema").optional<import("effect/Schema").String>;
+    readonly headers: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+    readonly queryParams: import("effect/Schema").optional<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").Struct<{
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>]>>>;
+    readonly auth: import("effect/Schema").optional<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"none">;
+    }>, import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"header">;
+        readonly headerName: import("effect/Schema").String;
+        readonly secretId: import("effect/Schema").String;
+        readonly prefix: import("effect/Schema").optional<import("effect/Schema").String>;
+    }>, import("effect/Schema").Struct<{
+        readonly kind: import("effect/Schema").Literal<"oauth2">;
+        readonly connectionId: import("effect/Schema").String;
+        readonly clientIdSecretId: import("effect/Schema").optional<import("effect/Schema").String>;
+        readonly clientSecretSecretId: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").String>>;
+    }>]>>;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").StringTree<never>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<import("effect/Schema").Struct<{
+    readonly updated: import("effect/Schema").Boolean;
+}>>, import("effect/unstable/httpapi/HttpApiEndpoint").Json<typeof import("@executor-js/api").InternalError | typeof McpConnectionError | typeof McpToolDiscoveryError>, never, never>, false>>;
+/**
+ * Errors any MCP extension method may surface. The first four are
+ * plugin-domain tagged errors that flow directly to clients (4xx, each
+ * carrying its own `HttpApiSchema` status). `StorageFailure` covers
+ * raw backend failures (`StorageError`) plus `UniqueViolationError`;
+ * the HTTP edge (`@executor-js/api`'s `withCapture`) translates
+ * `StorageError` to the opaque `InternalError({ traceId })` at Layer
+ * composition. `UniqueViolationError` passes through — plugins can
+ * `Effect.catchTag` it if they want a friendlier user-facing error.
+ */
+export type McpExtensionFailure = McpConnectionError | McpToolDiscoveryError | StorageFailure;
 export interface McpPluginExtension {
-    readonly probeEndpoint: (endpoint: string) => Effect.Effect<McpProbeResult, Error>;
+    readonly probeEndpoint: (input: string | McpProbeEndpointInput) => Effect.Effect<McpProbeResult, McpExtensionFailure>;
     readonly addSource: (config: McpSourceConfig) => Effect.Effect<{
         readonly toolCount: number;
         readonly namespace: string;
-    }, Error>;
-    readonly removeSource: (namespace: string) => Effect.Effect<void>;
-    readonly refreshSource: (namespace: string) => Effect.Effect<{
+    }, McpExtensionFailure>;
+    readonly removeSource: (namespace: string, scope: string) => Effect.Effect<void, McpExtensionFailure>;
+    readonly refreshSource: (namespace: string, scope: string) => Effect.Effect<{
         readonly toolCount: number;
-    }, Error>;
-    readonly startOAuth: (input: McpOAuthStartInput) => Effect.Effect<McpOAuthStartResponse, Error>;
-    readonly completeOAuth: (input: McpOAuthCompleteInput) => Effect.Effect<McpOAuthCompleteResponse, Error>;
-    /** Fetch the full stored source by namespace (or null if missing) */
-    readonly getSource: (namespace: string) => Effect.Effect<McpStoredSource | null>;
-    /** Update config for an existing remote MCP source */
-    readonly updateSource: (namespace: string, input: McpUpdateSourceInput) => Effect.Effect<void>;
+    }, McpExtensionFailure>;
+    readonly getSource: (namespace: string, scope: string) => Effect.Effect<McpStoredSource | null, McpExtensionFailure>;
+    readonly updateSource: (namespace: string, scope: string, input: McpUpdateSourceInput) => Effect.Effect<void, McpExtensionFailure>;
 }
-export declare const mcpPlugin: (options?: {
-    readonly bindingStore?: McpBindingStore;
-}) => ExecutorPlugin<"mcp", McpPluginExtension>;
+export {};

package/dist/sdk/probe-shape.d.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+export type McpShapeProbeResult = 
+/** Server answered initialize successfully — either a 2xx with a
+ *  JSON-RPC payload, or a 401 + WWW-Authenticate: Bearer (RFC 6750
+ *  challenge) that the MCP auth spec requires. */
+{
+    readonly kind: "mcp";
+    readonly requiresAuth: boolean;
+}
+/** Endpoint is reachable but the response does not look like MCP. */
+ | {
+    readonly kind: "not-mcp";
+    readonly reason: string;
+}
+/** Transport-level failure (DNS, TLS, timeout, abort, ...). */
+ | {
+    readonly kind: "unreachable";
+    readonly reason: string;
+};
+export interface ProbeOptions {
+    /** Injected for tests. Defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Abort the request after this many ms. Default 8000. */
+    readonly timeoutMs?: number;
+    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, string>;
+}
+/**
+ * Hit `endpoint` with a JSON-RPC `initialize` POST and classify the
+ * response according to the MCP authorization spec.
+ *
+ * Returns `{kind: "mcp"}` only when the endpoint either:
+ *   - answers with 2xx (unauth-OK MCP server), or
+ *   - responds 401 with a `Bearer` WWW-Authenticate challenge.
+ *
+ * Anything else (400, 404, 200-with-HTML, 200-with-GraphQL-errors, ...)
+ * is classified `not-mcp`. Transport errors surface as `unreachable`.
+ */
+export declare const probeMcpEndpointShape: (endpoint: string, options?: ProbeOptions) => Effect.Effect<McpShapeProbeResult>;

package/dist/sdk/probe-shape.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/stdio-connector.d.ts

@@ -0,0 +1,8 @@
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+export type StdioTransportConfig = {
+    readonly command: string;
+    readonly args?: ReadonlyArray<string>;
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+};
+export declare const createStdioTransport: (config: StdioTransportConfig) => StdioClientTransport;

package/dist/sdk/stored-source.d.ts

@@ -1,114 +1,40 @@
 import { Schema } from "effect";
-declare const McpStoredSourceSchema_base: Schema.Class<McpStoredSourceSchema, {
-    namespace: typeof Schema.String;
-    name: typeof Schema.String;
-    config: Schema.Union<[Schema.Struct<{
-        transport: Schema.Literal<["remote"]>;
-        endpoint: typeof Schema.String;
-        remoteTransport: Schema.optionalWith<Schema.Literal<["streamable-http", "sse", "auto"]>, {
-            default: () => "auto";
-        }>;
-        queryParams: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        headers: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        auth: Schema.Union<[Schema.Struct<{
-            kind: Schema.Literal<["none"]>;
+declare const McpStoredSourceSchema_base: Schema.Class<McpStoredSourceSchema, Schema.Struct<{
+    readonly namespace: Schema.String;
+    readonly name: Schema.String;
+    readonly config: Schema.Union<readonly [Schema.Struct<{
+        readonly transport: Schema.Literal<"remote">;
+        readonly endpoint: Schema.String;
+        readonly remoteTransport: Schema.withConstructorDefault<Schema.optionalKey<Schema.Literals<readonly ["streamable-http", "sse", "auto"]>>>;
+        readonly queryParams: Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Struct<{
+            readonly secretId: Schema.String;
+            readonly prefix: Schema.optional<Schema.String>;
+        }>]>>>;
+        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Struct<{
+            readonly secretId: Schema.String;
+            readonly prefix: Schema.optional<Schema.String>;
+        }>]>>>;
+        readonly auth: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"none">;
         }>, Schema.Struct<{
-            kind: Schema.Literal<["header"]>;
-            headerName: typeof Schema.String;
-            secretId: typeof Schema.String;
-            prefix: Schema.optional<typeof Schema.String>;
+            readonly kind: Schema.Literal<"header">;
+            readonly headerName: Schema.String;
+            readonly secretId: Schema.String;
+            readonly prefix: Schema.optional<Schema.String>;
         }>, Schema.Struct<{
-            kind: Schema.Literal<["oauth2"]>;
-            accessTokenSecretId: typeof Schema.String;
-            refreshTokenSecretId: Schema.NullOr<typeof Schema.String>;
-            tokenType: Schema.optionalWith<typeof Schema.String, {
-                default: () => string;
-            }>;
-            expiresAt: Schema.NullOr<typeof Schema.Number>;
-            scope: Schema.NullOr<typeof Schema.String>;
+            readonly kind: Schema.Literal<"oauth2">;
+            readonly connectionId: Schema.String;
+            readonly clientIdSecretId: Schema.optional<Schema.String>;
+            readonly clientSecretSecretId: Schema.optional<Schema.NullOr<Schema.String>>;
         }>]>;
     }>, Schema.Struct<{
-        transport: Schema.Literal<["stdio"]>;
-        command: typeof Schema.String;
-        args: Schema.optional<Schema.Array$<typeof Schema.String>>;
-        env: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        cwd: Schema.optional<typeof Schema.String>;
+        readonly transport: Schema.Literal<"stdio">;
+        readonly command: Schema.String;
+        readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly cwd: Schema.optional<Schema.String>;
     }>]>;
-}, Schema.Struct.Encoded<{
-    namespace: typeof Schema.String;
-    name: typeof Schema.String;
-    config: Schema.Union<[Schema.Struct<{
-        transport: Schema.Literal<["remote"]>;
-        endpoint: typeof Schema.String;
-        remoteTransport: Schema.optionalWith<Schema.Literal<["streamable-http", "sse", "auto"]>, {
-            default: () => "auto";
-        }>;
-        queryParams: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        headers: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        auth: Schema.Union<[Schema.Struct<{
-            kind: Schema.Literal<["none"]>;
-        }>, Schema.Struct<{
-            kind: Schema.Literal<["header"]>;
-            headerName: typeof Schema.String;
-            secretId: typeof Schema.String;
-            prefix: Schema.optional<typeof Schema.String>;
-        }>, Schema.Struct<{
-            kind: Schema.Literal<["oauth2"]>;
-            accessTokenSecretId: typeof Schema.String;
-            refreshTokenSecretId: Schema.NullOr<typeof Schema.String>;
-            tokenType: Schema.optionalWith<typeof Schema.String, {
-                default: () => string;
-            }>;
-            expiresAt: Schema.NullOr<typeof Schema.Number>;
-            scope: Schema.NullOr<typeof Schema.String>;
-        }>]>;
-    }>, Schema.Struct<{
-        transport: Schema.Literal<["stdio"]>;
-        command: typeof Schema.String;
-        args: Schema.optional<Schema.Array$<typeof Schema.String>>;
-        env: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        cwd: Schema.optional<typeof Schema.String>;
-    }>]>;
-}>, never, {
-    readonly name: string;
-} & {
-    readonly namespace: string;
-} & {
-    readonly config: {
-        readonly endpoint: string;
-        readonly transport: "remote";
-        readonly remoteTransport: "streamable-http" | "sse" | "auto";
-        readonly queryParams?: {
-            readonly [x: string]: string;
-        } | undefined;
-        readonly headers?: {
-            readonly [x: string]: string;
-        } | undefined;
-        readonly auth: {
-            readonly kind: "none";
-        } | {
-            readonly secretId: string;
-            readonly kind: "header";
-            readonly headerName: string;
-            readonly prefix?: string | undefined;
-        } | {
-            readonly kind: "oauth2";
-            readonly scope: string | null;
-            readonly accessTokenSecretId: string;
-            readonly refreshTokenSecretId: string | null;
-            readonly tokenType: string;
-            readonly expiresAt: number | null;
-        };
-    } | {
-        readonly transport: "stdio";
-        readonly command: string;
-        readonly args?: readonly string[] | undefined;
-        readonly env?: {
-            readonly [x: string]: string;
-        } | undefined;
-        readonly cwd?: string | undefined;
-    };
-}, {}, {}>;
+}>, {}>;
 export declare class McpStoredSourceSchema extends McpStoredSourceSchema_base {
 }
 export type McpStoredSourceSchemaType = typeof McpStoredSourceSchema.Type;

package/dist/sdk/test-utils.d.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import * as http from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type McpTestServer = {
+    readonly url: string;
+    readonly httpServer: http.Server;
+    /** Number of MCP sessions created (each connect = 1 session) */
+    readonly sessionCount: () => number;
+};
+/**
+ * Spin up a real HTTP server backed by a fresh `McpServer` per session,
+ * with proper session routing via `mcp-session-id`. The factory is invoked
+ * once per new session, so tools registered inside it are isolated per
+ * connection (matching the SDK's own server/transport coupling).
+ */
+export declare const serveMcpServer: (factory: () => McpServer) => Effect.Effect<McpTestServer, Error, import("effect/Scope").Scope>;