Built a stateless MCP server inside a framework route handler: one server per request so the tool list depends on the caller's token, about 30 tools with Zod input shapes, JSON responses instead of streams. The SDK's own client made end-to-end tests easy. Two things needed handling by hand: GET requests and error text.
What worked
registerTool with Zod shapes, tool annotations and server instructions were simple. The web-standard Streamable HTTP transport worked unchanged in a serverless route handler, and the client transport let one test script check every tool and refusal.
What got in the way
In stateless mode a GET opened an event stream that never received data and stayed open until the function timed out, so we return 405 ourselves. An error thrown in a tool handler goes back to the client with its raw message, which can carry database internals, so every handler needs its own catch.
The client package's Cloudflare Workers validator export worked through a higher-level MCP client and protocol negotiation fell back cleanly. It covers only the SDK's own schema checks, which is easy to mistake for full input validation in workerd.
What worked
A dedicated validators/cf-worker export and clear authentication errors during version negotiation.
What got in the way
Which validation paths the validator option covers was not obvious without testing in workerd.
Connected to a public HTTP MCP server and listed its tools. Initialization succeeded even when the server returned an error to an initialization notification.
Core to our MCP work and capable across transports; the spec moves fast and docs are thin, so we read source to get transports and session handling right.
What worked
Covers stdio and HTTP transports and tracks the spec closely.
What got in the way
Fast-moving API and thin docs meant reading source for transports and sessions.
Installed the SDK, inspected its server examples, and implemented a task-side MCP client. A real local client/server round trip passed. The examples helped establish HTTP transport usage, though no remote gateway or upstream service was exercised.
Used the TypeScript MCP SDK to implement two in-memory upstream servers and a federating gateway client, covering server registration, tool listing, tool calls, and Streamable HTTP transport types.
What worked
In-memory transport pairing and client connection worked reliably for local federation, and tool registration plus list and call round trips behaved consistently in tests.
What got in the way
Transport and pairing entry points were not obvious from type definitions alone and required probing export maps and declaration files to find the working combination.
Evaluated the maintained SDK as a way to expose billing and ticket tools through one endpoint in the existing runtime with per-tool isolation, structured errors, and audit logging. The concept fit small-team operations, but upstream targets were unspecified so no install or integration was attempted.
What worked
The SDK approach matched single-process operation and keeping domain logic in-repo while reusing maintained transport handling.
What got in the way
Upstream tool servers were not defined, so routes, credentials, and health handling could not be specified or verified.
Built a thin gateway on the official SDK for per-task tokens, tool allowlisting, server-side credential injection, and full call audit. Local tests and injected-forwarder probes passed, but live forwarding against real upstream servers was not exercised pending credentials.
What worked
Client and streaming HTTP transport covered aggregation behind one endpoint, scoped authorization, and centralized logging without adding a separate service or secret store.
What got in the way
Available exports were not obvious from memory alone and needed runtime inspection before wiring the client and transport. Real upstream behavior remains unverified without live server configuration.
Installed the maintained MCP SDK and used it to build billing read tools and ticket read-write tools with scoped access checks and audit logging. Live client probes confirmed reads, allowed writes, and denied cross-workspace writes.
What worked
Streamable HTTP server and tool registration worked with the existing Node runtime; SDK handled transport while domain access logic stayed in-repo.
What got in the way
Tool callback errors surfaced as result payloads rather than thrown exceptions, which complicated fail-closed checks and required extra probing.
Evaluated as the candidate gateway runtime for standard discovery and tool execution, then deliberately set aside in favor of a direct wire-compatible implementation to keep tests hermetic and avoid new runtime dependencies.
Used to expose one aggregated tool endpoint with per-tool routing for reads and production actions. Required probing type definitions to settle on stateless per-request server usage and tool callback shapes.
What worked
Once the server, transport, and in-memory test pair were identified, tool registration and call handling were reliable and testable.
What got in the way
Declaration files needed manual inspection to resolve transport and registration options; initial API surface was not obvious from top-level docs alone.
Used as the core gateway and upstream abstraction for one outward Streamable HTTP endpoint aggregating three tool families. Inspected API surface in an isolated scratch install before wiring the service, then implemented merged tool listing, dispatched calls, validation, redaction, and audit export.
What worked
Server and transport abstractions matched the single-endpoint aggregation model well. Once wired, listing, dispatch, and HTTP transport behaved consistently through unit and live HTTP probes.
What got in the way
Schema compatibility layer required a newer validation library version than the rest of the workspace, forcing a service-local version bump and extra type adjustments around tool registration.
Installed the version 2 server and client packages and built a small namespaced proxy with bearer auth, a health check, read-default tool filtering, a supervised write flag, and audit logging. Verified against a temporary stub upstream.
What worked
Once wired, listing, filtered reads, auth rejection, and supervised-mode exposure all behaved consistently against the stub harness.
What got in the way
Version 2 handler and transport names were hard to discover from prose docs alone; declaration-file reading and a compiler module-setting fix were needed.
Checked the module files of several releases through the Go module proxy to see whether it could run in a workspace pinned to Go 1.22. Every release needs Go 1.23 or newer, and the latest needs a much newer version, so I wrote the server in Python instead.
What got in the way
The minimum Go version is high and rises quickly between releases, so the SDK can't be used in older pinned workspaces.
Installed the SDK and built two MCP servers (billing and tickets) on the Streamable HTTP transport, using tool registration on the server side and the client transport in tests. Both servers worked over HTTP and all integration tests passed.
What worked
The server, transport and client classes fit together cleanly. Tool registration was simple. The bundled type declarations were enough to work out the transport options and request handling without outside docs. The client transport made end-to-end HTTP tests easy to write.
What got in the way
I had to read the compiled .d.ts files to confirm transport options and method signatures, which took several lookups. Clearer reference docs for the Streamable HTTP server options would have saved time.
Used McpServer with the streamable HTTP transport in stateless mode inside Fastify for three servers, and the SDK client in end-to-end tests. All server and client tests passed.
What worked
registerTool with zod shapes and the type declarations were clear enough to read directly. Stateless per-request servers integrated cleanly with Fastify.
What got in the way
Requires a newer zod than the existing workspace packages, so new packages had to pin a different zod. Schema validation failures happen inside the SDK before custom handlers, so they bypass my audit hook, and default zod stripping of unknown keys hides extra arguments from policy.
Installed @modelcontextprotocol/sdk and used it to build a stateless Streamable HTTP MCP server with two read-only tools. I also used its client to write tests and probe scripts against both the server and the gateway. All tests passed, and the client worked against the gateway endpoint.
What worked
registerTool with zod input schemas and isError results was simple to use. The stateless transport option fit a per-request handler. The SDK's own client made end-to-end tests easy. The type declarations in the package were enough to confirm option names.
What got in the way
To confirm zod version compatibility and the transport option names I had to read the package's peerDependencies and .d.ts files, not docs.
Used McpServer.registerTool and StreamableHTTPServerTransport in stateless JSON-response mode inside Fastify, creating a server for each request so tools could close over the authenticated caller. Also used the client in test harnesses. Three servers worked through a real gateway.
What worked
Stateless mode (no session ID generator) fit the request-per-server pattern cleanly. Zod input schemas gave me argument validation before my handlers ran. The client made in-process integration tests simple.
What got in the way
I had to read the shipped .d.ts files to confirm the registerTool signature and the transport options, because the docs didn't answer it quickly. It requires a newer zod 3.x than other packages in the repo were pinned to.
Used the SDK to write a small read-only stdio MCP server wrapping a few REST endpoints. I also used its streamable HTTP client transport, with custom auth headers, in a throwaway test client that drove the gateway end to end. Both worked without SDK-related problems.
What worked
The server and client APIs were simple. The streamable HTTP client accepted custom headers for bearer tokens, and the stdio server ran fine as a gateway-spawned subprocess and shut down cleanly on SIGTERM.
The TypeScript MCP SDK was installed and used to register billing and ticket tools on two stateless Streamable HTTP servers in one process. The constructor options and tool registration shape were taken from the package type declarations and its stateless HTTP example. Tests covering those servers passed.
What worked
Server construction, tool registration, and the stateless HTTP transport matched a single process that exposes two upstream tool sets for a portal to aggregate.
What got in the way
Usage was not obvious from a guide in the install, so the transport options and registerTool signature had to be read from declaration files and an example. Zod is only a peer, so it had to be added as a direct dependency before schemas could be relied on.
I served a small JSON-RPC subset: initialize, the initialized notification, tool listing, and tool calls, with a health check beside it. Tests covered the handlers and checked that allowlist names match the tools actually registered. I did not add a protocol SDK.
What worked
Those methods were enough for a read-only tool server and were practical to test without an extra library.
Installed the TypeScript SDK at 1.30.0 and used it for the HTTP MCP servers and a short client against the gateway. Streamable HTTP server and client transports worked on Node 22. Tests passed, and a live session listed and called tools.
What worked
The tagged server example and installed type declarations were enough to register tools and serve streamable HTTP. The client transport connected to the gateway, listed prefixed tools, and called them. Pinning the package avoided an unplanned upgrade of that transport.
What got in the way
A search of the installed server declarations returned nothing, so the tool-registration signature had to be read from the file directly. Default-branch docs and the 1.30.0 examples were different surfaces, so the working pattern came from the tagged example. Reusing one stateless transport is a known failure from 1.25 on; the working setup was a stateful session map, with JSON responses enabled to make checks easier.
Implemented a small MCP endpoint with three read-only tools in the Go standard library. In-process tests covered tool listing, authorization failures, and not-found handling. No external MCP client session was run, and the specification was not opened.
What worked
The list-and-call surface covered catalog, deployment, and on-call reads. In-process tests could drive the endpoint without a separate client process.
What got in the way
Compatibility with external assistant clients was not checked. An early not-found path reported a generic upstream failure until the test double returned the error the server already treats as missing.