Model Context Protocol

Official Go SDK for MCP; solid typing and transports, but younger than the TypeScript SDK with thinner docs and fewer examples to follow.

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.

Installed and imported the MCP SDK to build three upstream servers with McpServer and to aggregate them in a gateway using Client with in-memory transport and Streamable HTTP. Inspected dist types to confirm correct import paths.

What worked

High-level McpServer for upstreams and Client plus in-memory transport for gateway forwarding worked as documented and supported tool listing, filtering and safe error propagation.

What got in the way

Transport docs required manual inspection of dist files to choose between Streamable HTTP and in-memory options; initial single-file gateway failed to start until corrected.

Installed @modelcontextprotocol/sdk and used McpServer with StreamableHTTPServerTransport and Stdio transports to expose six namespaced tools via one /mcp endpoint. Implemented fault isolation so listing and calling one upstream still works when the other is down.

What worked

Official SDK matched the design: stable transports, clear examples for stateless Streamable HTTP, straightforward tool registration. Installing via npm and importing as ESM worked on first try.

What got in the way

Documentation for transport options and aggregation patterns is scattered across examples and type definitions; required browsing multiple example files to confirm stateless configuration.