Your MCP server answers tool calls on localhost. Behind nginx, a long import tool looks hung: the agent sees no progress for the whole call, then every event at once. After the container restarts, each connected agent gets 404 on its next call, and the health check you pointed at the server answers 400.
What you get
You will end up with an MCP server image behind nginx with TLS, live progress events, a health route, and a stateless transport that agents do not notice restarting. This is for you if you host a Streamable HTTP server for remote agents.
Short answer
Build the MCP server into a small image and put nginx or Traefik in front to handle TLS. On the
MCP location set proxy_buffering off, or nginx holds every progress event from a Go MCP SDK
server until the tool returns. Give the server a /healthz route, a container restart policy, and
a stateless transport, so a restarted server answers agents that initialized before it went down.
You will need
A container host with TLS certificates, Node 22 or later, Go, and nginx 1.24 or Traefik. The
transport here is Streamable HTTP; choose between stdio and Streamable HTTP for an MCP
server first if that is still open. The servers wrap the Bookshelf
document, five operations on /books. Verified 2026-11-21.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| FastMCP under uvicorn | Your tools are Python and you want a health route in one decorator | 62 PyPI distributions and 70.3 MB of packages to patch for one server | You want one static binary, or your team ships no Python |
| Hey API client in a TypeScript MCP SDK server | A Node team that writes its tools by hand over a typed client | 95 npm packages with the SDK and zod, and every tool written and tested by you | You want the tools generated, or a smaller image |
| Kiota client in a Go MCP SDK server | Go, and a client library from the generator Microsoft supports | 23 Go modules in the binary, and a server and tools you write yourself | You want the server generated from the document |
| sdkgen go-mcp target | One 15 MB static binary generated from the document | Read-only tools by default, no health route or Origin check, and sessions lost on restart until edited | You need tools shaped per operation, or progress events |
Voxgig maintains sdkgen, one of four ways on this page to serve the same API as MCP tools. The row for it lists what it costs.
The go-mcp binary links the fewest modules, eight, but its stock main.go needs edits before it
suits a container. The Kiota server is the smaller file at 13.6 MB, with 23 modules to patch. The
hand-written servers give you every line of the tool code, which also makes every line yours to
maintain.
Generate the Go server and give it a health route
record.sh scaffolds the project with the go and go-mcp targets and builds the server:
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target go --target go-mcp > scaffold.log 2>&1
(cd bookshelf-sdk/.sdk && npm run generate > ../../generate.log 2>&1)
(cd bookshelf-sdk/go-mcp && CGO_ENABLED=0 go build -trimpath -o "$WORK/mcp-stock" .)
The stock server keeps a session per client, checks no Origin, and sends every path to the MCP
handler, so it has no health route. main.go is rendered from a fragment in the project,
.sdk/src/cmp/go-mcp/fragment/main.fragment.go, and an edit there survives regeneration. Three
edits turn on the SDK’s Stateless option, add /healthz, and wrap the handler in net/http’s
CrossOriginProtection:
case "http":
handler := mcp.NewStreamableHTTPHandler(
func(r *http.Request) *mcp.Server { return server },
&mcp.StreamableHTTPOptions{Stateless: true},
)
mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte("{\"status\":\"ok\"}\n"))
})
// go-sdk v1.6.0 checks no Origin unless asked; net/http refuses a cross-origin browser request.
mux.Handle("/", http.NewCrossOriginProtection().Handler(handler))
npx voxgig-sdkgen doctor reports the edit as customized, and its exit code is 0:
cat evidence/doctor.txt
CUSTOMIZED (an add merges its updates into it): src/cmp/go-mcp/fragment/main.fragment.go
.sdk matches the scaffold (0 additive, 1 customized)
exit 0
The stock project regenerated on the newest releases on npm wrote the same main.go:
cat evidence/go-mcp-newest.txt
# @voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1
go-mcp/main.go: identical to the 4.44.3 file
tools: bookshelf_list bookshelf_load
deploy/Dockerfile.go-mcp builds the binary in golang:1.25 and copies it into the
gcr.io/distroless/static-debian12:nonroot image.
That image has no shell, so the file declares no HEALTHCHECK; point the platform’s HTTP probe at
/healthz. What each runtime ships, measured by record.sh:
cat evidence/footprint.txt
runtime what ships packages
sdkgen go-mcp binary 15.1 MB 8 Go modules linked in
Kiota client, Go MCP SDK 13.6 MB 23 Go modules linked in
Node, TypeScript MCP SDK 17.4 MB of node_modules 95 npm packages, zod included
Python, FastMCP and uvicorn 70.3 MB of site-packages 62 PyPI distributions
# the Python mcp package FastMCP installed: 2.3.0, with sse_starlette 3.7.0
Serve TLS from nginx and turn buffering off
nginx buffers the responses of an upstream server by default. Its
proxy_buffering
directive passes a response on as it arrives only when set to off, or when the upstream answers
X-Accel-Buffering: no.1 The MCP location:
location = /mcp {
proxy_pass http://mcp:8080;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_buffering off;
proxy_read_timeout 300s;
}
record.sh ran nginx 1.24.0 on this file, with a self-signed certificate, and once more with the
proxy_buffering line removed, in front of the Node server and the Kiota server on go-sdk. The
tool adds three books, and the stand-in API takes 300 ms per write:
cat evidence/nginx-buffering.txt
# nginx version: nginx/1.24.0 (Ubuntu)
import_books, 3 titles, 300 ms per write: progress events that arrived before the result
server nginx.conf as committed proxy_buffering line removed X-Accel-Buffering
TypeScript MCP SDK 1.32.2 3 of 3 3 of 3 no
Go MCP SDK v1.6.0 3 of 3 0 of 3 not sent
The TypeScript SDK opts its stream out with the header, so nginx streams it either way. go-sdk
v1.6.0 sends no such header, so its progress waited for the result. go-mcp’s tools for this document
send no progress events, so the line matters there once a tool of yours does. proxy.mjs models the same
rule without nginx:
node buffering.mjs
import_books, 3 titles, 300 ms per write: progress events that arrived before the result
buffering on, the default 3 of 3
buffering on, X-Accel-Buffering ignored 0 of 3
buffering off 3 of 3
Traefik was not run. Its service
reference
says a response it recognizes as streaming is flushed immediately, whatever
responseForwarding.flushInterval holds, so it documents no buffering line to turn off. It also sets passHostHeader to true by default, which
matters below.
Wrap a Kiota or Hey API client in a server you write
Kiota 1.39.0 has no MCP output. Its --help lists these commands, and generate -l accepts these
languages:
cat evidence/kiota.txt
# kiota 1.39.0: its commands, from kiota --help
generate search download show info update login logout rpc
# the languages kiota generate -l accepts
CSharp|Dart|Go|HTTP|Java|PHP|Python|Ruby|TypeScript
None of the 39 pages in the table of contents of its documentation is about MCP. Hey API’s documentation index and its full-text companion do not mention MCP either. So the substitute for both is a server you write around the generated client.
kiotaserver/main.go is that server in Go. Two tools on go-sdk v1.6.0 call the Kiota builder’s
Get and Post, behind a guard that refuses an unknown Host or Origin. kiota-http-go 1.7.0 gzips
every request body by default, and the stand-in, like any API that refuses Content-Encoding on
requests, answers 415, so the server turns compression off:
func NewBookshelf(base string) (*client.BookshelfClient, error) {
middleware, err := kiotahttp.GetDefaultMiddlewaresWithOptions(kiotahttp.NewCompressionOptionsReference(false))
if err != nil {
return nil, err
}
adapter, err := kiotahttp.NewNetHttpRequestAdapterWithParseNodeFactoryAndSerializationWriterFactoryAndHttpClient(
&authentication.AnonymousAuthenticationProvider{}, nil, nil, kiotahttp.GetDefaultClient(middleware...))
record.sh built it and ran its Go tests:
cat evidence/kiotaserver-test.txt
--- PASS: TestGuardRefusesUnknownHostAndOrigin
--- PASS: TestToolsCallTheApiThroughTheKiotaClient
--- PASS: TestToolsReportAFailedApiCallAsIsError
PASS
ok example.com/kiotaserver
server.mjs is the substitute in TypeScript: the
official TypeScript SDK serves the tools,
and each one calls the Hey API client.
server.registerTool(
'import_books',
{
description: 'Add each title to the shelf, one write at a time, reporting progress before each.',
inputSchema: { titles: z.array(z.string().min(1)).min(1).max(10) },
The Hey API output requires only its own files, so the image carries the 95 packages of the lock file.
Check it worked
node --test mcp.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
The tests stop the Node server with SIGKILL, start it again on the same port, and call a tool
with the session the client already held. They run check-deploy.mjs on each broken neighbor of
the committed files: proxy_buffering off commented out, a base image with no tag, a missing
EXPOSE, or a compose service whose image nobody builds. They also hold the stand-in to every
field of the Book schema.
When it goes wrong
record.sh ran the stock go-mcp server, the edited one and the Kiota server behind the same nginx:
cat evidence/go-mcp-behind-nginx.txt
stock server, Host from proxy_pass ($proxy_host): tools/call 200 result lists Dune
stock server, Host $host from the client: initialize 403
body: Forbidden: invalid Host header "mcp.example.com"
stock server, Origin https://evil.example: initialize 200
stock server, GET /healthz: 400
edited server, GET /healthz: 200 {"status":"ok"}
edited server, Origin https://evil.example: initialize 403
stock server restarted, the old session id: tools/call 404 -
stock server restarted, after a fresh initialize: tools/call 200 result lists Dune
edited server, no session id at all: tools/call 200 result lists Dune
edited server restarted, no session id: tools/call 200 result lists Dune
Kiota server, no session id: tools/call 200 result lists Dune
Kiota server, Origin https://evil.example: initialize 403
Every request answers 403. go-sdk v1.6.0
refuses a request that arrives on a loopback address with a Host that is not loopback. nginx on the
same host with proxy_set_header Host $host, or Traefik with its default passHostHeader, trips
it. Drop the Host line for that layout, or set DisableLocalhostProtection and check the Host
yourself against a list.
A page on another site gets an answer from the stock server. go-sdk v1.6.0 applies no Origin check unless one is configured, and the binding makes that check a MUST. Wrap the handler, as the fragment edit does.
Agents get 404 after a restart. The stock server keeps sessions in memory, and the transport specification leaves the recovery to the client.2 Make the server stateless, as the fragment edit does.
The health check fails on a healthy server. The stock binary sends every path to the MCP handler, which answered the probe’s GET with 400. Add the route, and point the container check at it.
When not to do this
Do not put a buffering proxy in front of a server whose tools stream progress without testing one slow call through it. Each SDK answers the question differently, and the preceding table is the test.
Do not ship the stock go-mcp main.go to a container platform that restarts on a failed health
check. On the Bookshelf document sdkgen’s go-mcp target generated two read-only tools,
bookshelf_list and bookshelf_load, because its model sets tool: write: *false. Its server
keeps a session per client and has no health route, so it needs the fragment edit first. A Kiota
client inside a go-sdk server suits a Go team that wants each tool shaped by hand. Hey API with the TypeScript SDK suits a Node team, because the SDK
opts its stream out of nginx’s buffering for you.
Do not run several replicas of a stateful server behind one proxy without sticky routing. A stateless server needs none.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen
4.44.3, go-sdk v1.6.0, @modelcontextprotocol/sdk 1.32.2, Hey API 0.99.0, Kiota 1.39.0, nginx
1.24.0, and FastMCP 4.2.4 with uvicorn 0.54.0. No container image was built and neither Dockerfile
nor compose.yaml was run, because this sandbox has a Docker client and no Docker daemon.
check-deploy.mjs reads the three files instead. nginx ran once, through record.sh, and its
results are committed under evidence/. FastMCP was installed to measure its packages and not run;
its health route comes from its HTTP deployment guide. Traefik was not run, and its settings come
from its service reference.
Footnotes
-
nginx reads several response fields named
X-Accel-, and itsproxy_ignore_headersentry listsX-Accel-Bufferingwith the version 1.1.6 beside it. The TypeScript MCP SDK 1.32.2 sets that field on its SSE responses, as does the Pythonmcppackage 2.3.0 throughsse-starlette3.7.0. go-sdk v1.6.0 never writes it. ↩︎ Back to text -
The Streamable HTTP section says a server may end a session at any time and MUST then answer its id with 404. A client that receives the 404 MUST start a new session with a fresh initialize. A server that keeps its sessions in memory ends all of them when it restarts. ↩︎ Back to text