@effect-uai/mcp 0.12.1

package/src/internal/protocol.ts

@@ -0,0 +1,67 @@
+/**
+ * The `Protocol` seam: everything that differs between the stateless
+ * 2026-07-28 revision and the 2025-06-18 handshake era, behind one interface.
+ * `modern.ts` and `legacy.ts` implement it independently and never import each
+ * other; `Client.connect` picks one, once, from the probes.
+ *
+ * The negotiated `version` is the single source of truth. There is no separate
+ * era label: nothing branches on it at runtime, so carrying one would only
+ * create state that can drift out of sync with the version.
+ */
+import { Effect, Option, Predicate, type Scope } from "effect"
+import type { McpError } from "../McpError.js"
+import type { Inbound, McpConnection, SendMeta } from "./rpc.js"
+import {
+  decodeUnsupportedVersionData,
+  type McpMethod,
+  MODERN_ERROR_CODES,
+  type ProtocolVersion,
+  type ServerInfo,
+} from "./schema.js"
+
+export type Protocol = {
+  readonly version: ProtocolVersion
+  readonly serverInfo: ServerInfo
+  /** Wrap outgoing params: modern adds the `_meta` envelope, legacy passes through. */
+  readonly envelope: (method: McpMethod, params: unknown) => unknown
+  /** Per-request transport hints: modern headers, or the legacy session id. */
+  readonly meta: (method: McpMethod, params: unknown) => SendMeta
+  /** Answer a server-initiated frame. Modern servers never send one. */
+  readonly onInbound: (inbound: Inbound) => Effect.Effect<void>
+}
+
+/**
+ * Probe for one protocol era. `None` means "not this era, try the next"; a
+ * failure means the server is this era but unusable (no mutual version).
+ */
+export type ProtocolProbe = (
+  connection: McpConnection,
+) => Effect.Effect<Option.Option<Protocol>, McpError, Scope.Scope>
+
+const isProtocolError = Predicate.isTagged("McpProtocolError")
+
+/**
+ * A `-32020` / `-32021` / `-32022` reply, which is the spec's era
+ * discriminator: it proves the peer speaks a modern version, so the client
+ * corrects and retries rather than falling back to `initialize`. `supported`
+ * carries the versions a `-32022` offered, decoded through the schema so a
+ * server that adds fields cannot break it.
+ */
+export type ModernRejection = {
+  readonly code: number
+  readonly supported: ReadonlyArray<string>
+}
+
+export const modernRejection = (error: McpError): Option.Option<ModernRejection> =>
+  isProtocolError(error)
+    ? Option.fromNullishOr(error.code).pipe(
+        Option.filter((code) => MODERN_ERROR_CODES.has(code)),
+        Option.map((code) => ({ code, supported: supportedVersions(error.raw) })),
+      )
+    : Option.none()
+
+const supportedVersions = (raw: unknown): ReadonlyArray<string> =>
+  decodeUnsupportedVersionData(Predicate.hasProperty(raw, "data") ? raw.data : undefined).pipe(
+    Option.flatMap((data) => Option.fromNullishOr(data.supported)),
+    Option.getOrElse((): ReadonlyArray<string> => []),
+  )

package/src/internal/protocols/2025-06-18.ts

@@ -0,0 +1,110 @@
+/**
+ * Protocol revision 2025-06-18: the handshake era, and the compatibility mode
+ * this client keeps for the servers that have not migrated. Also serves
+ * 2025-11-25, which is wire-compatible for a tools-only client (see
+ * `2025-11-25.ts`).
+ *
+ * Three things differ from the stateless era, and they are all here:
+ * an `initialize` exchange at connect, a negotiated version echoed on every
+ * later request, and server-initiated requests arriving on the connection.
+ *
+ * The HTTP session id (`Mcp-Session-Id`) is deliberately *not* here: it is a
+ * transport concern that `httpTransport` captures and echoes on its own, so
+ * this file stays transport-agnostic.
+ */
+import { Effect, Option, type Scope } from "effect"
+import { type McpError, McpUnsupportedProtocol } from "../../McpError.js"
+import type { Protocol, ProtocolProbe } from "../protocol.js"
+import type { Inbound, McpConnection, SendMeta } from "../rpc.js"
+import {
+  asProtocolVersion,
+  CLIENT_INFO,
+  CODE_METHOD_NOT_FOUND,
+  decodeInitializeResult,
+  LEGACY_VERSION,
+  type McpMethod,
+  type ProtocolVersion,
+  type ServerInfo,
+} from "../schema.js"
+
+const UNKNOWN_SERVER: ServerInfo = { name: "unknown" }
+
+/**
+ * Legacy params travel bare: no `_meta` envelope. Only the negotiated version
+ * rides along, and on HTTP only as a header.
+ */
+const makeProtocol = (
+  connection: McpConnection,
+  version: ProtocolVersion,
+  serverInfo: ServerInfo,
+): Protocol => ({
+  version,
+  serverInfo,
+  envelope: (_method: McpMethod, params: unknown) => params ?? {},
+  meta: (): SendMeta => ({ headers: { "MCP-Protocol-Version": version } }),
+  onInbound: (inbound: Inbound) => answer(connection, inbound),
+})
+
+/**
+ * Legacy servers may send requests to the client. We are a headless tools
+ * client: answer `ping` so the connection stays healthy, and decline
+ * everything else (sampling, elicitation, roots) with method-not-found rather
+ * than leaving the server waiting.
+ */
+const answer = (connection: McpConnection, inbound: Inbound): Effect.Effect<void> =>
+  Option.match(inbound.id, {
+    // A notification expects no reply.
+    onNone: () => Effect.void,
+    onSome: (id) =>
+      (inbound.method === "ping"
+        ? connection.respond(id, {})
+        : connection.respondError(
+            id,
+            CODE_METHOD_NOT_FOUND,
+            `${inbound.method} is not supported by this client`,
+          )
+      ).pipe(Effect.ignore),
+  })
+
+/**
+ * Run the `initialize` handshake. Unlike the stateless probe there is nothing
+ * to fall back to afterwards, so a failure here propagates rather than
+ * yielding `None`: this is the last era we speak.
+ */
+export const probe: ProtocolProbe = (connection: McpConnection) =>
+  handshake(connection).pipe(Effect.map(Option.some))
+
+const handshake = (connection: McpConnection): Effect.Effect<Protocol, McpError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const raw = yield* connection.request("initialize", {
+      protocolVersion: LEGACY_VERSION,
+      capabilities: {},
+      clientInfo: CLIENT_INFO,
+    })
+    const result = yield* decodeInitializeResult(raw).pipe(
+      Effect.mapError(
+        () =>
+          new McpUnsupportedProtocol({
+            offered: [],
+            reason: "initialize returned an undecodable result",
+          }),
+      ),
+    )
+    // The server picks the version; we either speak it or we stop here.
+    const version = yield* Option.match(asProtocolVersion(result.protocolVersion), {
+      onNone: () =>
+        Effect.fail(
+          new McpUnsupportedProtocol({
+            offered: [result.protocolVersion],
+            reason: `the server negotiated ${result.protocolVersion}, which this client does not support`,
+          }),
+        ),
+      onSome: Effect.succeed,
+    })
+
+    // Required by the spec before any other request; failing to send it is
+    // fatal to the session, so it is not ignored.
+    yield* connection.notify("notifications/initialized")
+
+    return makeProtocol(connection, version, result.serverInfo ?? UNKNOWN_SERVER)
+  })

package/src/internal/protocols/2025-11-25.ts

@@ -0,0 +1,8 @@
+/**
+ * Protocol revision 2025-11-25. Wire-compatible with 2025-06-18 for a
+ * tools-only client: its additions (icons, tasks, OIDC discovery) do not touch
+ * `initialize`, `tools/list` or `tools/call`, so it re-exports that
+ * implementation rather than duplicating it. If a future delta does affect our
+ * subset, it belongs here.
+ */
+export { probe } from "./2025-06-18.js"

package/src/internal/protocols/2026-07-28.test.ts

@@ -0,0 +1,131 @@
+import { describe, it } from "@effect/vitest"
+import { Cause, Effect, Option, Queue, Stream } from "effect"
+import { expect } from "vitest"
+import { McpUnsupportedProtocol } from "../../McpError.js"
+import { open, type SendMeta, type Transport } from "../rpc.js"
+import { LATEST_VERSION, META_PROTOCOL_VERSION } from "../schema.js"
+import { probe } from "./2026-07-28.js"
+
+type Sent = { readonly frame: string; readonly meta: SendMeta | undefined }
+
+/**
+ * A scripted server: `reply` sees each parsed request and returns the JSON-RPC
+ * body to answer with (`undefined` stays silent).
+ */
+const scripted = (reply: (request: Record<string, any>) => unknown) =>
+  Effect.gen(function* () {
+    const inbox = yield* Queue.make<string, Cause.Done>()
+    const sent: Array<Sent> = []
+    const transport: Transport = {
+      send: (frame, meta) =>
+        Effect.gen(function* () {
+          sent.push({ frame, meta })
+          const request = JSON.parse(frame) as Record<string, any>
+          const body = reply(request)
+          if (body !== undefined) {
+            yield* Queue.offer(
+              inbox,
+              JSON.stringify({ jsonrpc: "2.0", id: request.id, ...(body as object) }),
+            )
+          }
+        }),
+      messages: Stream.fromQueue(inbox),
+    }
+    return { transport, sent }
+  })
+
+// Spec-conformant servers identify themselves in the result's `_meta`, not at
+// the top level. Verified against Hugging Face, which does exactly this.
+const discovered = {
+  result: {
+    resultType: "complete",
+    supportedVersions: [LATEST_VERSION],
+    capabilities: { tools: {} },
+    _meta: {
+      "io.modelcontextprotocol/serverInfo": {
+        name: "scripted",
+        version: "1.0.0",
+        title: "Scripted",
+        websiteUrl: "https://example.com",
+      },
+    },
+  },
+}
+
+const unsupported = (supported: ReadonlyArray<string>) => ({
+  error: {
+    code: -32022,
+    message: "Unsupported protocol version",
+    data: { supported, requested: "1900-01-01" },
+  },
+})
+
+const runProbe = (reply: (request: Record<string, any>) => unknown) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const { sent, transport } = yield* scripted(reply)
+      const connection = yield* open(transport, () => Effect.void)
+      const protocol = yield* probe(connection)
+      return { protocol, sent }
+    }),
+  )
+
+describe("2026-07-28 probe", () => {
+  it.effect("negotiates the stateless protocol from a server/discover result", () =>
+    Effect.gen(function* () {
+      const { protocol } = yield* runProbe(() => discovered)
+      const value = Option.getOrThrow(protocol)
+      expect(value.version).toBe(LATEST_VERSION)
+      expect(value.serverInfo.name).toBe("scripted")
+    }),
+  )
+
+  it.effect("keeps the MCP-Protocol-Version header equal to the _meta version", () =>
+    Effect.gen(function* () {
+      // A divergence between the two is exactly what servers reject with -32020.
+      const { sent } = yield* runProbe(() => discovered)
+      const frame = JSON.parse(sent[0]?.frame ?? "{}") as Record<string, any>
+      expect(sent[0]?.meta?.headers?.["MCP-Protocol-Version"]).toBe(
+        frame.params._meta[META_PROTOCOL_VERSION],
+      )
+    }),
+  )
+
+  it.effect("retries on a mutually supported version after a -32022", () =>
+    Effect.gen(function* () {
+      let attempts = 0
+      const { protocol, sent } = yield* runProbe(() => {
+        attempts += 1
+        return attempts === 1 ? unsupported([LATEST_VERSION]) : discovered
+      })
+      expect(sent).toHaveLength(2)
+      expect(Option.getOrThrow(protocol).version).toBe(LATEST_VERSION)
+    }),
+  )
+
+  it.effect("fails typed when the server shares no supported version", () =>
+    Effect.gen(function* () {
+      const exit = yield* Effect.exit(runProbe(() => unsupported(["1999-01-01"])))
+      const error = exit._tag === "Failure" ? Cause.squash(exit.cause) : undefined
+      expect(error).toBeInstanceOf(McpUnsupportedProtocol)
+      expect((error as McpUnsupportedProtocol).offered).toEqual(["1999-01-01"])
+    }),
+  )
+
+  it.effect("yields None on a non-modern error so the caller falls back to the handshake", () =>
+    Effect.gen(function* () {
+      const { protocol } = yield* runProbe(() => ({
+        error: { code: -32601, message: "Method not found" },
+      }))
+      expect(Option.isNone(protocol)).toBe(true)
+    }),
+  )
+
+  it.effect("Base64-encodes an Mcp-Name that is not header-safe", () =>
+    Effect.gen(function* () {
+      const { protocol } = yield* runProbe(() => discovered)
+      const { headers } = Option.getOrThrow(protocol).meta("tools/call", { name: "Hello, 世界" })
+      expect(headers?.["Mcp-Name"]).toBe("=?base64?SGVsbG8sIOS4lueVjA==?=")
+    }),
+  )
+})

package/src/internal/protocols/2026-07-28.ts

@@ -0,0 +1,152 @@
+/**
+ * Protocol revision 2026-07-28: the stateless era. No handshake and no
+ * session; every request self-describes via `_meta`, mirrored into the HTTP
+ * request headers. Servers never send requests back, so `onInbound` has
+ * nothing to answer.
+ *
+ * Files here are named for the revision they implement. A later revision that
+ * keeps this wire shape gets its own file re-exporting this one.
+ */
+import { Effect, Encoding, Option, Predicate, Record, type Scope } from "effect"
+import { type McpError, McpUnsupportedProtocol } from "../../McpError.js"
+import { modernRejection, type Protocol, type ProtocolProbe } from "../protocol.js"
+import type { McpConnection, SendMeta } from "../rpc.js"
+import {
+  asProtocolVersion,
+  CLIENT_INFO,
+  decodeDiscoverResult,
+  META_CLIENT_CAPABILITIES,
+  META_CLIENT_INFO,
+  META_SERVER_INFO,
+  META_PROTOCOL_VERSION,
+  type McpMethod,
+  LATEST_VERSION,
+  type ProtocolVersion,
+  type ServerInfo,
+} from "../schema.js"
+
+const UNKNOWN_SERVER: ServerInfo = { name: "unknown" }
+
+/**
+ * Which param field carries the subject name mirrored into `Mcp-Name`, per
+ * method. Keyed by string rather than `McpMethod` so the methods a later
+ * revision adds need no cast here.
+ */
+const NAME_FIELD: Record<string, string> = {
+  "tools/call": "name",
+  "prompts/get": "name",
+  "resources/read": "uri",
+}
+
+const subjectName = (method: McpMethod, params: unknown): Option.Option<string> =>
+  Record.get(NAME_FIELD, method).pipe(
+    Option.flatMap((field) => Record.get(asRecord(params), field)),
+    Option.filter(Predicate.isString),
+  )
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  Predicate.isObject(value) ? value : {}
+
+const SENTINEL = /^=\?base64\?.*\?=$/
+// Visible ASCII only, no leading or trailing space (RFC 9110 field values).
+const HEADER_SAFE = /^[\x21-\x7e]([\x20-\x7e]*[\x21-\x7e])?$/
+
+/**
+ * Header values outside the safe set (and any literal that would be mistaken
+ * for the marker) ride the spec's Base64 sentinel form.
+ */
+export const headerValue = (raw: string): string =>
+  HEADER_SAFE.test(raw) && !SENTINEL.test(raw) ? raw : `=?base64?${Encoding.encodeBase64(raw)}?=`
+
+const makeProtocol = (version: ProtocolVersion, serverInfo: ServerInfo): Protocol => ({
+  version,
+  serverInfo,
+
+  envelope: (_method, params) => ({
+    ...asRecord(params),
+    _meta: {
+      [META_PROTOCOL_VERSION]: version,
+      [META_CLIENT_INFO]: CLIENT_INFO,
+      [META_CLIENT_CAPABILITIES]: {},
+    },
+  }),
+
+  // `MCP-Protocol-Version` MUST equal the `_meta` version or the server
+  // answers -32020, so both are minted from the same `version`.
+  meta: (method, params): SendMeta => ({
+    headers: {
+      "MCP-Protocol-Version": version,
+      "Mcp-Method": method,
+      ...subjectName(method, params).pipe(
+        Option.map((name) => ({ "Mcp-Name": headerValue(name) })),
+        Option.getOrElse(() => ({})),
+      ),
+    },
+  }),
+
+  onInbound: () => Effect.void,
+})
+
+/**
+ * Probe with `server/discover`. A `DiscoverResult` means modern. A modern
+ * error code means modern-but-rejected: on `-32022` retry with a mutual
+ * version. Anything else yields `None`, i.e. "try the legacy handshake".
+ */
+export const probe: ProtocolProbe = (connection) =>
+  discover(connection, LATEST_VERSION).pipe(
+    Effect.map(Option.some),
+    Effect.catch((error) =>
+      Option.match(modernRejection(error), {
+        // Not a modern error shape, so this is not a modern server.
+        onNone: () => Effect.succeedNone,
+        onSome: ({ supported }) => retryOnMutualVersion(connection, supported),
+      }),
+    ),
+  )
+
+const retryOnMutualVersion = (
+  connection: McpConnection,
+  offered: ReadonlyArray<string>,
+): Effect.Effect<Option.Option<Protocol>, McpError, Scope.Scope> =>
+  Option.match(Option.firstSomeOf(offered.map(asProtocolVersion)), {
+    onNone: () =>
+      Effect.fail(
+        new McpUnsupportedProtocol({
+          offered,
+          reason: "the server is modern but shares no protocol version with this client",
+        }),
+      ),
+    onSome: (version) => discover(connection, version).pipe(Effect.map(Option.some)),
+  })
+
+const discover = (
+  connection: McpConnection,
+  version: ProtocolVersion,
+): Effect.Effect<Protocol, McpError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const probing = makeProtocol(version, UNKNOWN_SERVER)
+    const raw = yield* connection.request(
+      "server/discover",
+      probing.envelope("server/discover", {}),
+      probing.meta("server/discover", {}),
+    )
+    const result = yield* decodeDiscoverResult(raw).pipe(
+      Effect.mapError(
+        () =>
+          new McpUnsupportedProtocol({
+            offered: [],
+            reason: "server/discover returned an undecodable result",
+          }),
+      ),
+    )
+    // The server answered on `version`, so it supports it; prefer it, and only
+    // fall to its list if it somehow disagrees.
+    const agreed = result.supportedVersions.includes(version)
+      ? version
+      : Option.getOrElse(
+          Option.firstSomeOf(result.supportedVersions.map(asProtocolVersion)),
+          () => version,
+        )
+    const identity = result._meta?.[META_SERVER_INFO] ?? result.serverInfo ?? UNKNOWN_SERVER
+    return makeProtocol(agreed, identity)
+  })

package/src/internal/rpc.test.ts

@@ -0,0 +1,156 @@
+import { Cause, Effect, Exit, Fiber, Option, Queue, Stream } from "effect"
+import { describe, expect, it } from "vitest"
+import { McpProtocolError, McpTransportClosed } from "../McpError.js"
+import { type Inbound, open, type SendMeta, type Transport } from "./rpc.js"
+
+type Sent = { readonly frame: string; readonly meta: SendMeta | undefined }
+
+// In-memory Transport stub: a scripted `messages` queue + a recording `send`.
+const makeStub = Effect.gen(function* () {
+  const queue = yield* Queue.make<string, Cause.Done>()
+  const sent: Array<Sent> = []
+  const transport: Transport = {
+    send: (frame, meta) => Effect.sync(() => void sent.push({ frame, meta })),
+    messages: Stream.fromQueue(queue),
+  }
+  return {
+    transport,
+    sent,
+    push: (message: unknown) => Queue.offer(queue, JSON.stringify(message)),
+    pushRaw: (frame: string) => Queue.offer(queue, frame),
+    close: Queue.end(queue),
+  }
+})
+
+// The reader fiber consumes frames asynchronously, so tests wait on the
+// observable effect rather than sleeping.
+const until = (pred: () => boolean): Effect.Effect<void> =>
+  Effect.suspend(() => (pred() ? Effect.void : Effect.flatMap(Effect.yieldNow, () => until(pred))))
+
+const noInbound = (): Effect.Effect<void> => Effect.void
+
+const frames = (sent: ReadonlyArray<Sent>): ReadonlyArray<Record<string, unknown>> =>
+  sent.map((s) => JSON.parse(s.frame) as Record<string, unknown>)
+
+const failureOf = (exit: Exit.Exit<unknown, unknown>): unknown =>
+  Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined
+
+describe("rpc correlation core", () => {
+  it("correlates out-of-order replies by id", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      const first = yield* Effect.forkChild(connection.request("tools/list"))
+      const second = yield* Effect.forkChild(connection.request("tools/call", { name: "a" }))
+      yield* until(() => stub.sent.length === 2)
+      // Reply to the second request first: correlation must be by id, not order.
+      yield* stub.push({ jsonrpc: "2.0", id: 2, result: { fromSecond: true } })
+      yield* stub.push({ jsonrpc: "2.0", id: 1, result: { fromFirst: true } })
+      const secondResult = yield* Fiber.join(second)
+      const firstResult = yield* Fiber.join(first)
+      return { firstResult, secondResult, sent: frames(stub.sent) }
+    })
+    const { firstResult, secondResult, sent } = await Effect.runPromise(Effect.scoped(program))
+    expect(firstResult).toEqual({ fromFirst: true })
+    expect(secondResult).toEqual({ fromSecond: true })
+    expect(sent[0]).toEqual({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} })
+    expect(sent[1]?.params).toEqual({ name: "a" })
+  })
+
+  it("maps a JSON-RPC error reply to McpProtocolError with its code", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      const fiber = yield* Effect.forkChild(Effect.exit(connection.request("tools/call")))
+      yield* until(() => stub.sent.length === 1)
+      yield* stub.push({ jsonrpc: "2.0", id: 1, error: { code: -32602, message: "bad params" } })
+      return yield* Fiber.join(fiber)
+    })
+    const error = failureOf(await Effect.runPromise(Effect.scoped(program)))
+    expect(error).toBeInstanceOf(McpProtocolError)
+    const protocolError = error as McpProtocolError
+    expect(protocolError.code).toBe(-32602)
+    expect(protocolError.method).toBe("tools/call")
+    expect(protocolError.reason).toBe("bad params")
+  })
+
+  it("fails every pending request when the transport closes", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      const first = yield* Effect.forkChild(Effect.exit(connection.request("tools/list")))
+      const second = yield* Effect.forkChild(Effect.exit(connection.request("tools/call")))
+      yield* until(() => stub.sent.length === 2)
+      yield* stub.close
+      return [yield* Fiber.join(first), yield* Fiber.join(second)]
+    })
+    const exits = await Effect.runPromise(Effect.scoped(program))
+    for (const exit of exits) {
+      expect(failureOf(exit)).toBeInstanceOf(McpTransportClosed)
+    }
+  })
+
+  it("routes server-initiated requests and notifications to onInbound", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const inbound: Array<Inbound> = []
+      yield* open(stub.transport, (message) => Effect.sync(() => void inbound.push(message)))
+      yield* stub.push({ jsonrpc: "2.0", id: 9, method: "ping" })
+      yield* stub.push({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })
+      yield* until(() => inbound.length === 2)
+      return inbound
+    })
+    const inbound = await Effect.runPromise(Effect.scoped(program))
+    expect(inbound[0]?.method).toBe("ping")
+    expect(inbound[0]?.id).toEqual(Option.some(9))
+    expect(inbound[1]?.method).toBe("notifications/tools/list_changed")
+    expect(Option.isNone(inbound[1]?.id ?? Option.none())).toBe(true)
+  })
+
+  it("notify sends an id-less frame", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      yield* connection.notify("notifications/initialized")
+      return frames(stub.sent)
+    })
+    const sent = await Effect.runPromise(Effect.scoped(program))
+    expect(sent[0]).toEqual({ jsonrpc: "2.0", method: "notifications/initialized" })
+  })
+
+  it("fails pending requests on an id-less error instead of hanging forever", async () => {
+    // JSON-RPC returns a null id for errors raised before the request could be
+    // attributed (parse failure, rejected content type). Nothing correlates, so
+    // the caller must fail rather than await a reply that cannot arrive.
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      const fiber = yield* Effect.forkChild(Effect.exit(connection.request("server/discover")))
+      yield* until(() => stub.sent.length === 1)
+      yield* stub.push({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" },
+      })
+      return yield* Fiber.join(fiber)
+    })
+    const error = failureOf(await Effect.runPromise(Effect.scoped(program)))
+    expect(error).toBeInstanceOf(McpProtocolError)
+    expect((error as McpProtocolError).code).toBe(-32700)
+  })
+
+  it("survives replies for unknown ids and non-JSON frames", async () => {
+    const program = Effect.gen(function* () {
+      const stub = yield* makeStub
+      const connection = yield* open(stub.transport, noInbound)
+      yield* stub.push({ jsonrpc: "2.0", id: 99, result: {} })
+      yield* stub.pushRaw("this is not json")
+      const fiber = yield* Effect.forkChild(connection.request("tools/list"))
+      yield* until(() => stub.sent.length === 1)
+      yield* stub.push({ jsonrpc: "2.0", id: 1, result: { ok: true } })
+      return yield* Fiber.join(fiber)
+    })
+    const result = await Effect.runPromise(Effect.scoped(program))
+    expect(result).toEqual({ ok: true })
+  })
+})