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

Source: https://voxgig.com/howto/run-an-mcp-server-in-a-container

- Audience: platform-team
- Level: intermediate
- Languages: go, typescript, python
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](/howto/choose-an-mcp-transport) 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](https://gofastmcp.com/docs/deployment/http) | 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](https://heyapi.dev/docs/openapi/typescript/get-started) | 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](https://learn.microsoft.com/en-us/openapi/kiota/overview) | 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](https://github.com/voxgig/sdkgen) | 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:

```bash title="record.sh"
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`](https://pkg.go.dev/net/http#CrossOriginProtection):

```go title="sdkgen/main.fragment.go"
	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:

```bash
cat evidence/doctor.txt
```

```text output
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`:

```bash
cat evidence/go-mcp-newest.txt
```

```text output
# @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`](https://github.com/GoogleContainerTools/distroless) 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`:

```bash
cat evidence/footprint.txt
```

```text output
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`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#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:

```nginx title="deploy/nginx.conf"
    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:

```bash
cat evidence/nginx-buffering.txt
```

```text output
# 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:

```bash
node buffering.mjs
```

```text output
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](https://doc.traefik.io/traefik/reference/routing-configuration/http/load-balancing/service/)
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:

```bash
cat evidence/kiota.txt
```

```text output
# 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](https://heyapi.dev/llms.txt) 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:

```go title="kiotaserver/main.go"
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:

```bash
cat evidence/kiotaserver-test.txt
```

```text output
--- PASS: TestGuardRefusesUnknownHostAndOrigin
--- PASS: TestToolsCallTheApiThroughTheKiotaClient
--- PASS: TestToolsReportAFailedApiCallAsIsError
PASS
ok  	example.com/kiotaserver
```

`server.mjs` is the substitute in TypeScript: the
[official TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) serves the tools,
and each one calls the Hey API client.

```js title="server.mjs"
  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

```bash
node --test mcp.test.mjs
```

```text output
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:

```bash
cat evidence/go-mcp-behind-nginx.txt
```

```text output
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](https://github.com/modelcontextprotocol/go-sdk/blob/v1.6.0/mcp/streamable.go)
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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
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

- [Choose between stdio and Streamable HTTP for an MCP server](/howto/choose-an-mcp-transport)

- [Generate an MCP server from an OpenAPI document](/howto/generate-an-mcp-server-from-openapi)

- [Add a health endpoint agents can poll](/howto/add-a-health-endpoint-for-agents)

- [Build an MCP server in Go over an existing HTTP client](/howto/build-an-mcp-server-in-go)

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

[^1]: nginx reads several response fields named `X-Accel-`, and its
[`proxy_ignore_headers`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#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.

[^2]: The [Streamable HTTP section](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
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.