How-to › Expose your API to agents

How to run an MCP server in a container behind a reverse proxy#

Run an MCP server image behind nginx with buffering off, plus a health route, an Origin check, and a stateless transport so a restart needs no manual step.

Audience
Platform team
Level
intermediate
Topic
Host, transport and secure an MCP server
Languages
Go, TypeScript and Python
Verified

Read first: Choose between stdio and Streamable HTTP for an MCP server

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
FastMCP under uvicornYour tools are Python and you want a health route in one decorator62 PyPI distributions and 70.3 MB of packages to patch for one serverYou want one static binary, or your team ships no Python
Hey API client in a TypeScript MCP SDK serverA Node team that writes its tools by hand over a typed client95 npm packages with the SDK and zod, and every tool written and tested by youYou want the tools generated, or a smaller image
Kiota client in a Go MCP SDK serverGo, and a client library from the generator Microsoft supports23 Go modules in the binary, and a server and tools you write yourselfYou want the server generated from the document
sdkgen go-mcp targetOne 15 MB static binary generated from the documentRead-only tools by default, no health route or Origin check, and sessions lost on restart until editedYou 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.

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

  1. nginx reads several response fields named X-Accel-, and its proxy_ignore_headers entry lists X-Accel-Buffering with the version 1.1.6 beside it. The TypeScript MCP SDK 1.32.2 sets that field on its SSE responses, as does the Python mcp package 2.3.0 through sse-starlette 3.7.0. go-sdk v1.6.0 never writes it. ↩︎ Back to text

  2. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.