@effect-uai/mcp 0.12.1

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@effect-uai/mcp",
+  "version": "0.12.1",
+  "description": "Model Context Protocol client provider for @effect-uai/core.",
+  "keywords": [
+    "agents",
+    "ai",
+    "effect",
+    "mcp",
+    "model-context-protocol",
+    "tools"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/mcp",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/providers/mcp"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./Client": {
+      "types": "./dist/Client.d.mts",
+      "import": "./dist/Client.mjs"
+    },
+    "./Toolkit": {
+      "types": "./dist/Toolkit.d.mts",
+      "import": "./dist/Toolkit.mjs"
+    },
+    "./McpError": {
+      "types": "./dist/McpError.d.mts",
+      "import": "./dist/McpError.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.111",
+    "@effect/vitest": "4.0.0-rc.111",
+    "effect": "4.0.0-rc.111",
+    "typescript": "^7.0.2",
+    "@effect-uai/core": "0.12.1"
+  },
+  "peerDependencies": {
+    "@effect-uai/core": ">=0.5.0 <1",
+    "effect": ">=4.0.0-rc.111 <5.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Client.ts

@@ -0,0 +1,180 @@
+/**
+ * `connect` opens a scoped MCP client: transport -> rpc core -> protocol probe.
+ * The protocol era is a property of the server, so it is negotiated once here
+ * and fixed for the connection's lifetime. The client surface is era-uniform.
+ */
+import { Context, Effect, Layer, Option, Ref, type Scope } from "effect"
+import type { HttpClient } from "effect/unstable/http"
+import type { ChildProcessSpawner } from "effect/unstable/process"
+import { McpConnectFailed, type McpError, McpProtocolError } from "./McpError.js"
+import { Auth, type TokenSource } from "./internal/auth.js"
+import * as Handshake from "./internal/protocols/2025-06-18.js"
+import * as Stateless from "./internal/protocols/2026-07-28.js"
+import type { Protocol } from "./internal/protocol.js"
+import { type McpConnection, open } from "./internal/rpc.js"
+import {
+  type CallToolResult,
+  decodeCallToolResult,
+  decodeListToolsResult,
+  LATEST_VERSION,
+  type McpMethod,
+  type ProtocolVersion,
+  type ServerInfo,
+  type ToolInfo,
+} from "./internal/schema.js"
+import * as HttpTransport from "./internal/httpTransport.js"
+import * as StdioTransport from "./internal/stdioTransport.js"
+
+export { Auth, type TokenSource }
+
+/** `auto` runs the probe; a pinned version skips detection. */
+export type ProtocolPin = "auto" | ProtocolVersion
+
+export type McpClientConfig =
+  | {
+      readonly transport: "http"
+      readonly url: string
+      /** Static, non-auth headers sent on every request. */
+      readonly headers?: Record<string, string>
+      /** Omit for a public server. See `Auth` for the three shapes. */
+      readonly auth?: Auth
+      readonly protocol?: ProtocolPin
+    }
+  | {
+      readonly transport: "stdio"
+      readonly command: string
+      readonly args?: ReadonlyArray<string>
+      readonly env?: Record<string, string>
+      readonly cwd?: string
+      readonly protocol?: ProtocolPin
+    }
+
+/**
+ * Services a client needs, by transport. Both are listed because the config is
+ * a runtime value: an app that only uses one still provides the other's layer,
+ * which is cheap (`FetchHttpClient.layer` / `NodeServices.layer`).
+ */
+export type McpRequirements = HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner
+
+export type McpServerInfo = ServerInfo & {
+  /** The negotiated protocol version: the only era signal callers need. */
+  readonly protocolVersion: ProtocolVersion
+}
+
+export type McpClient = {
+  readonly listTools: Effect.Effect<ReadonlyArray<ToolInfo>, McpError>
+  readonly callTool: (name: string, args: unknown) => Effect.Effect<CallToolResult, McpError>
+  readonly serverInfo: McpServerInfo
+}
+
+const undecodable = (method: McpMethod, detail: string, raw: unknown): McpError =>
+  new McpProtocolError({ method, reason: `undecodable ${method} result${detail}`, raw })
+
+const makeClient = (connection: McpConnection, protocol: Protocol): McpClient => {
+  const request = (method: McpMethod, params: unknown) =>
+    connection.request(method, protocol.envelope(method, params), protocol.meta(method, params))
+
+  return {
+    listTools: request("tools/list", {}).pipe(
+      Effect.flatMap((raw) =>
+        decodeListToolsResult(raw).pipe(
+          Effect.mapError(() => undecodable("tools/list", "", raw)),
+          Effect.map((result) => result.tools),
+        ),
+      ),
+    ),
+
+    callTool: (name, args) =>
+      request("tools/call", { name, arguments: args ?? {} }).pipe(
+        Effect.flatMap((raw) =>
+          decodeCallToolResult(raw).pipe(
+            Effect.mapError(() => undecodable("tools/call", ` for ${name}`, raw)),
+          ),
+        ),
+      ),
+
+    serverInfo: { ...protocol.serverInfo, protocolVersion: protocol.version },
+  }
+}
+
+/**
+ * Try the stateless protocol first, then the handshake era. The stateless
+ * probe yields `None` only when the server proves it is not stateless (an
+ * error that is not one of the recognized modern codes), which is exactly the
+ * spec's era discriminator. A pinned `protocol` skips detection.
+ *
+ * The result is cached for the connection's lifetime by the caller: era is a
+ * property of the server, not of a request.
+ */
+const negotiate = (
+  connection: McpConnection,
+  pin: ProtocolPin,
+): Effect.Effect<Protocol, McpError, Scope.Scope> => {
+  if (pin === LATEST_VERSION) return required(Stateless.probe(connection))
+  if (pin !== "auto") return required(Handshake.probe(connection))
+  return Stateless.probe(connection).pipe(
+    Effect.flatMap(
+      Option.match({
+        onNone: () => required(Handshake.probe(connection)),
+        onSome: Effect.succeed<Protocol>,
+      }),
+    ),
+  )
+}
+
+const required = (
+  probe: Effect.Effect<Option.Option<Protocol>, McpError, Scope.Scope>,
+): Effect.Effect<Protocol, McpError, Scope.Scope> =>
+  probe.pipe(
+    Effect.flatMap(
+      Option.match({
+        onNone: () =>
+          Effect.fail(
+            new McpConnectFailed({ reason: "the server does not speak a supported MCP protocol" }),
+          ),
+        onSome: Effect.succeed<Protocol>,
+      }),
+    ),
+  )
+
+/**
+ * Open a scoped client. The connection lives exactly as long as the enclosing
+ * scope, so `Effect.scoped`, a `Layer`, or `Stream.scoped` all give correct
+ * teardown with no explicit close.
+ */
+export const connect = (
+  config: McpClientConfig,
+): Effect.Effect<McpClient, McpError, Scope.Scope | McpRequirements> =>
+  Effect.gen(function* () {
+    const transport = yield* config.transport === "http"
+      ? HttpTransport.make(config)
+      : StdioTransport.make(config)
+
+    // Inbound handling belongs to the protocol, which is not chosen until the
+    // probe completes, so the reader reads it from a Ref that starts empty.
+    // Frames arriving before then can only be legacy noise; ignore them.
+    const protocolRef = yield* Ref.make(Option.none<Protocol>())
+    const connection = yield* open(transport, (inbound) =>
+      Ref.get(protocolRef).pipe(
+        Effect.flatMap(
+          Option.match({
+            onNone: () => Effect.void,
+            onSome: (protocol) => protocol.onInbound(inbound),
+          }),
+        ),
+      ),
+    )
+
+    const protocol = yield* negotiate(connection, config.protocol ?? "auto")
+    yield* Ref.set(protocolRef, Option.some(protocol))
+
+    return makeClient(connection, protocol)
+  })
+
+export class Mcp extends Context.Service<Mcp, McpClient>()(
+  "@betalyra/effect-uai/providers/mcp/Mcp",
+) {}
+
+/** DI convenience for the single-server app: connects when the layer builds. */
+export const layer = (config: McpClientConfig): Layer.Layer<Mcp, McpError, McpRequirements> =>
+  Layer.effect(Mcp, connect(config))

package/src/McpError.ts

@@ -0,0 +1,93 @@
+import { Data, Match } from "effect"
+
+/**
+ * Transport could not establish: DNS / TLS / non-2xx on the first request,
+ * a failed spawn, or a failed era probe. The raw transport error on `raw`.
+ */
+export class McpConnectFailed extends Data.TaggedError("McpConnectFailed")<{
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * Negotiation ended on a protocol version this client does not support
+ * (e.g. a 2025-03-26-only server, or a modern server whose `supported`
+ * list has no mutual version). `offered` is what the server proposed.
+ */
+export class McpUnsupportedProtocol extends Data.TaggedError("McpUnsupportedProtocol")<{
+  offered: ReadonlyArray<string>
+  reason?: string
+}> {}
+
+/**
+ * A JSON-RPC error reply (carrying its `code`), a reply that failed to
+ * decode, or an unsupported protocol feature (v1 fails `input_required`
+ * results here). `method` names the request that was in flight.
+ */
+export class McpProtocolError extends Data.TaggedError("McpProtocolError")<{
+  method?: string
+  code?: number
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * The connection dropped with a request in flight, or a legacy session
+ * expired (HTTP 404 on a known `Mcp-Session-Id`). Not resumable; the
+ * remedy is reconnecting and re-issuing the request.
+ */
+export class McpTransportClosed extends Data.TaggedError("McpTransportClosed")<{
+  method?: string
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * The server answered `401`. `resourceMetadataUrl` is the RFC 9728
+ * Protected Resource Metadata pointer parsed from `WWW-Authenticate`,
+ * when present; an OAuth layer starts discovery there.
+ */
+export class McpAuthRequired extends Data.TaggedError("McpAuthRequired")<{
+  resourceMetadataUrl?: string
+  wwwAuthenticate?: string
+}> {}
+
+/** A `TokenSource` / OAuth grant failed to mint or refresh a token. */
+export class McpAuthError extends Data.TaggedError("McpAuthError")<{
+  reason?: string
+  raw?: unknown
+}> {}
+
+export type McpError =
+  | McpConnectFailed
+  | McpUnsupportedProtocol
+  | McpProtocolError
+  | McpTransportClosed
+  | McpAuthRequired
+  | McpAuthError
+
+const withReason = (base: string, reason: string | undefined): string =>
+  reason === undefined ? base : `${base}: ${reason}`
+
+/**
+ * Short human-readable description of an error, for logs and model-facing
+ * failure messages (`Toolkit.describeFailures(McpError.describe)`). Prose,
+ * not a contract; branch on `_tag` instead.
+ */
+export const describe: (e: McpError) => string = Match.type<McpError>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    McpConnectFailed: (e) => withReason("could not connect to the MCP server", e.reason),
+    McpUnsupportedProtocol: (e) =>
+      `the MCP server only offers unsupported protocol versions (${e.offered.join(", ")})`,
+    McpProtocolError: (e) =>
+      withReason(
+        `the MCP server rejected ${e.method ?? "the request"}${
+          e.code === undefined ? "" : ` (${e.code})`
+        }`,
+        e.reason,
+      ),
+    McpTransportClosed: (e) => withReason("the MCP connection closed", e.reason),
+    McpAuthRequired: () => "the MCP server requires authentication",
+    McpAuthError: (e) => withReason("MCP authentication failed", e.reason),
+  }),
+)

package/src/Toolkit.ts

@@ -0,0 +1,109 @@
+/**
+ * Turn a connected MCP server into a core `Toolkit`, one `LocalTool` per MCP
+ * tool. Effectful because the tool list is fetched; composes with
+ * `Toolkit.compose` like any other kit.
+ */
+import { Effect, Option } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+import * as CoreToolkit from "@effect-uai/core/Toolkit"
+import type { McpClient } from "./Client.js"
+import { type McpError, McpProtocolError } from "./McpError.js"
+import {
+  type CallToolResult,
+  type ContentBlock,
+  isTextContent,
+  type ToolInfo,
+} from "./internal/schema.js"
+
+export type McpToolkitOptions = {
+  /** Namespace every tool as `<prefix>__<name>`; recommended when composing servers. */
+  readonly prefix?: string
+}
+
+/**
+ * The server owns validation, so the input schema is a passthrough: it carries
+ * the server's JSON Schema verbatim (the model sees the real thing) and
+ * accepts whatever the model produced. `strict: false` because server schemas
+ * are not written to OpenAI strict rules.
+ */
+const passthroughSchema = (tool: ToolInfo): Tool.ToolInputSchema<unknown> => ({
+  "~standard": {
+    version: 1,
+    vendor: "effect-uai-mcp",
+    validate: (value: unknown) => ({ value }),
+    jsonSchema: {
+      input: () => tool.inputSchema,
+      output: () => ({ type: "object" }),
+    },
+  },
+})
+
+const textOf = (block: ContentBlock): string =>
+  isTextContent(block) ? block.text : `[${block.type} content omitted]`
+
+/**
+ * Serialize a successful result for the model: `structuredContent` when the
+ * server provides it, otherwise the joined text blocks. Non-text blocks become
+ * a short placeholder until the loop grows a multimodal tool-output path.
+ */
+const outputOf = (result: CallToolResult): unknown =>
+  result.structuredContent ?? (result.content ?? []).map(textOf).join("\n")
+
+/**
+ * Two failure channels, deliberately: `isError` is the server telling the
+ * model it went wrong, so it becomes a model-visible `ToolFailed`; an
+ * `input_required` result is a protocol capability gap the model cannot fix,
+ * so it stays a typed `McpError`.
+ */
+const interpret = (
+  name: string,
+  result: CallToolResult,
+): Effect.Effect<unknown, McpError | Tool.ToolFailed> => {
+  if (result.isError === true) {
+    return Tool.fail(String(outputOf(result)), { kind: "tool_failed" })
+  }
+  if (result.resultType === "input_required") {
+    return Effect.fail(
+      new McpProtocolError({
+        method: "tools/call",
+        reason: `${name} requires interactive input (MRTR), unsupported by this client`,
+      }),
+    )
+  }
+  return Effect.succeed(outputOf(result))
+}
+
+const runTool =
+  (client: McpClient, name: string) =>
+  (input: unknown): Effect.Effect<unknown, McpError | Tool.ToolFailed> =>
+    client.callTool(name, input).pipe(Effect.flatMap((result) => interpret(name, result)))
+
+const toLocalTool = (client: McpClient, info: ToolInfo) =>
+  Tool.make({
+    name: info.name,
+    description: info.description ?? info.name,
+    inputSchema: passthroughSchema(info),
+    run: runTool(client, info.name),
+    strict: false,
+  })
+
+/**
+ * Build a `Toolkit` from the server's advertised tools. The list is snapshotted
+ * here; a tool that later vanishes surfaces through `Toolkit.run`'s graceful
+ * `unknown_tool` path.
+ */
+export const mcpToolkit = (
+  client: McpClient,
+  options?: McpToolkitOptions,
+): Effect.Effect<CoreToolkit.Toolkit, McpError> =>
+  client.listTools.pipe(
+    Effect.map((tools) => CoreToolkit.fromArray(tools.map((info) => toLocalTool(client, info)))),
+    Effect.map((kit) =>
+      Option.fromNullishOr(options?.prefix).pipe(
+        Option.match({
+          onNone: () => kit,
+          onSome: (prefix) => CoreToolkit.namespace(prefix, kit),
+        }),
+      ),
+    ),
+  )

package/src/index.ts

@@ -0,0 +1,3 @@
+export * as Client from "./Client.js"
+export * as McpError from "./McpError.js"
+export * as Toolkit from "./Toolkit.js"

package/src/internal/auth.ts

@@ -0,0 +1,48 @@
+/**
+ * Auth resolution for the HTTP transport. Era-blind: the stateless and
+ * handshake protocols both ride an OAuth 2.1 resource server, and neither
+ * knows this file exists. Tokens stay `Redacted` until the wire boundary.
+ */
+import { Data, Effect, Option, Redacted } from "effect"
+import type { McpAuthError } from "../McpError.js"
+
+/**
+ * An Effect yielding a bearer token. Any external OAuth, vault, or secret
+ * manager plugs in here. Read per request, so a producer minting expensive
+ * tokens caches internally (as `OAuth.clientCredentials` does).
+ */
+export type TokenSource = Effect.Effect<Redacted.Redacted<string>, McpAuthError>
+
+export type Auth = Data.TaggedEnum<{
+  /** A fixed token: the turnkey case for a token-gated server. */
+  Static: { readonly token: Redacted.Redacted<string>; readonly scheme?: string }
+  /** Bring your own, re-read before every request. */
+  TokenSource: { readonly token: TokenSource; readonly scheme?: string }
+  /** Built-in OAuth 2.1, which produces a `TokenSource` and rides the same seam. */
+  OAuth: { readonly source: TokenSource; readonly scheme?: string }
+}>
+
+export const Auth = Data.taggedEnum<Auth>()
+
+const tokenOf: (auth: Auth) => TokenSource = Auth.$match({
+  Static: ({ token }) => Effect.succeed(token),
+  TokenSource: ({ token }) => token,
+  OAuth: ({ source }) => source,
+})
+
+/**
+ * The `Authorization` header for one request, or none for a public server.
+ * `Redacted.value` is unwrapped only here.
+ */
+export const authHeaders = (
+  auth: Option.Option<Auth>,
+): Effect.Effect<Record<string, string>, McpAuthError> =>
+  Option.match(auth, {
+    onNone: () => Effect.succeed({}),
+    onSome: (a) =>
+      tokenOf(a).pipe(
+        Effect.map((token) => ({
+          authorization: `${a.scheme ?? "Bearer"} ${Redacted.value(token)}`,
+        })),
+      ),
+  })

package/src/internal/httpTransport.ts

@@ -0,0 +1,171 @@
+/**
+ * Streamable HTTP `Transport`. Each client message is its own POST; the server
+ * answers with either one JSON object or a request-scoped SSE stream ending in
+ * the JSON-RPC response, and a client MUST accept both. Frames from every
+ * in-flight POST demux into one `messages` stream, which the rpc core
+ * correlates by id.
+ *
+ * Interrupting a request aborts its POST, which is exactly the spec's
+ * cancellation signal (closing the response stream).
+ */
+import { Cause, Effect, Match, Option, Queue, Ref, type Scope, Stream } from "effect"
+import { HttpClient, HttpClientRequest, type HttpClientResponse } from "effect/unstable/http"
+import * as SSE from "@effect-uai/core/SSE"
+import {
+  McpAuthRequired,
+  McpConnectFailed,
+  type McpError,
+  McpProtocolError,
+  McpTransportClosed,
+} from "../McpError.js"
+import { type Auth, authHeaders } from "./auth.js"
+import type { SendMeta, Transport } from "./rpc.js"
+
+export type HttpConfig = {
+  readonly url: string
+  /** Static, non-auth headers applied to every request. */
+  readonly headers?: Record<string, string>
+  /** Omit for a public server. Resolved per request, so a rotating source works. */
+  readonly auth?: Auth
+}
+
+/** RFC 9728: the `resource_metadata` pointer on a 401's `WWW-Authenticate`. */
+const resourceMetadataUrl = (wwwAuthenticate: string): string | undefined =>
+  /resource_metadata="([^"]+)"/.exec(wwwAuthenticate)?.[1]
+
+const unauthorized = (response: HttpClientResponse.HttpClientResponse): McpError => {
+  const header = response.headers["www-authenticate"]
+  const pointer = header === undefined ? undefined : resourceMetadataUrl(header)
+  return new McpAuthRequired({
+    ...(pointer !== undefined ? { resourceMetadataUrl: pointer } : {}),
+    ...(header !== undefined ? { wwwAuthenticate: header } : {}),
+  })
+}
+
+/**
+ * A non-2xx that is not a 401. The body still matters: a modern server answers
+ * `400` for `-32022` / `-32021` / `-32020` and `404` for `-32601`, and era
+ * detection reads those codes off the JSON-RPC body. So the body is forwarded
+ * into `messages` whenever it parses as JSON, and only a bodyless failure
+ * becomes a transport error.
+ */
+const isJsonRpcBody = (body: string): boolean => body.trimStart().startsWith("{")
+
+export const make = (
+  config: HttpConfig,
+): Effect.Effect<Transport, McpError, Scope.Scope | HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const inbox = yield* Queue.make<string, Cause.Done>()
+    yield* Effect.addFinalizer(() => Queue.end(inbox))
+
+    // The legacy era's `Mcp-Session-Id` is a transport concern, not a protocol
+    // one: capture whatever the server mints and echo it from then on, so the
+    // protocol implementations stay transport-agnostic. Stateless servers
+    // never send one, and this stays empty.
+    const session = yield* Ref.make(Option.none<string>())
+
+    const post = (frame: string, meta?: SendMeta): Effect.Effect<void, McpError> =>
+      Effect.gen(function* () {
+        const sessionId = yield* Ref.get(session)
+        const auth = yield* authHeaders(Option.fromNullishOr(config.auth))
+        const request = HttpClientRequest.post(config.url).pipe(
+          HttpClientRequest.setHeaders({
+            "content-type": "application/json",
+            // Both response shapes are legal for any request.
+            accept: "application/json, text/event-stream",
+            ...config.headers,
+            ...auth,
+            ...meta?.headers,
+            ...Option.match(sessionId, {
+              onNone: () => ({}),
+              onSome: (id) => ({ "Mcp-Session-Id": id }),
+            }),
+          }),
+          // The content type must be set on the body: it overrides any header.
+          HttpClientRequest.bodyText(frame, "application/json"),
+        )
+        const response = yield* client
+          .execute(request)
+          .pipe(
+            Effect.mapError(
+              (cause) => new McpConnectFailed({ reason: "MCP request failed", raw: cause }),
+            ),
+          )
+        yield* captureSession(response)
+        yield* ingest(response)
+      })
+
+    const captureSession = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void> => {
+      const minted = response.headers["mcp-session-id"]
+      return minted === undefined ? Effect.void : Ref.set(session, Option.some(minted))
+    }
+
+    const ingest = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void, McpError> =>
+      Match.value(response.status).pipe(
+        Match.when(401, () => Effect.fail(unauthorized(response))),
+        Match.when(404, () => expiredOrBody(response)),
+        // 202 answers a notification and carries no body.
+        Match.when(202, () => Effect.void),
+        Match.orElse(() => readFrames(response)),
+      )
+
+    // A 404 against a session we hold means the server dropped it; the caller
+    // reconnects rather than retrying into a dead session.
+    const expiredOrBody = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void, McpError> =>
+      Ref.get(session).pipe(
+        Effect.flatMap((held) =>
+          Option.isSome(held)
+            ? Effect.fail(new McpTransportClosed({ reason: "the server expired this session" }))
+            : readBody(response),
+        ),
+      )
+
+    const readFrames = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void, McpError> =>
+      (response.headers["content-type"] ?? "").includes("text/event-stream")
+        ? readSse(response)
+        : readBody(response)
+
+    const readSse = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void, McpError> =>
+      response.stream.pipe(
+        SSE.fromBytes,
+        Stream.runForEach((event) => Queue.offer(inbox, event.data)),
+        Effect.mapError(
+          (cause) => new McpTransportClosed({ reason: "SSE stream failed", raw: cause }),
+        ),
+      )
+
+    const readBody = (
+      response: HttpClientResponse.HttpClientResponse,
+    ): Effect.Effect<void, McpError> =>
+      response.text.pipe(
+        Effect.mapError(
+          (cause) => new McpTransportClosed({ reason: "could not read response", raw: cause }),
+        ),
+        Effect.flatMap((body) =>
+          isJsonRpcBody(body)
+            ? Effect.asVoid(Queue.offer(inbox, body))
+            : Effect.fail(
+                new McpProtocolError({
+                  code: response.status,
+                  reason: `HTTP ${response.status} with a non-JSON-RPC body`,
+                  raw: body.slice(0, 500),
+                }),
+              ),
+        ),
+      )
+
+    // The POST runs on the caller's fiber so interruption aborts it, which is
+    // the spec's cancellation signal.
+    return { send: post, messages: Stream.fromQueue(inbox) } satisfies Transport
+  })