Designing a Self-Hosted MCP Gateway for Every AI Client

On this page
When I counted, Claude Code on my Mac had 25 MCP servers configured. Some ran as local processes started with npx or uvx. Two ran as local Docker containers, and both failed because Docker wasn’t on the PATH. Six ran as containers on one of our Docker hosts behind Traefik. Of those six, two were protected by an IP allow-list, one of those also required a bearer token, and four had no authentication at all. The tokens for the local ones sat in a JSON file in my home directory.
That works for one person with one tool. It falls apart the moment a second tool wants the same servers. This post is the design for fixing that, before any of it is built. The rest of the series follows the build.
The requirement that changed the design #
My first draft was built around Claude Code on a Mac. That’s the wrong starting point, and it took a few rounds to see it. The MCP servers have to work for every AI client we run:
- Claude Code and Codex, on macOS, Linux and Windows
- Hermes Agent
- our self-hosted AI stack: open-webui, its pipelines, and n8n
- Home Assistant
Once you list them, the question stops being “how does Claude Code authenticate” and becomes “what can each of these clients actually do”.
What the clients support #
I checked each client’s documentation instead of assuming.
| Client | Remote MCP auth options | Notes |
|---|---|---|
| Claude Code | OAuth, static headers, headersHelper (a command that prints fresh headers) | Client certificates are documented only for the OAuth sign-in requests |
| Codex | OAuth via codex mcp login, bearer token from an environment variable | Streamable HTTP only, no SSE |
| Hermes Agent | Static headers, auth: oauth (OAuth 2.1 with PKCE) | |
| Home Assistant | OAuth with application credentials | Its client docs mention SSE |
| open-webui, n8n | Whatever we configure | They run as workloads we control |
Two things stand out. OAuth with a short-lived bearer token is the only method every interactive client supports, which matches what the MCP specification itself defines. And mutual TLS from the client is not something you can rely on.
Phones and tablets: left out on purpose #
Claude’s mobile apps, claude.ai and the desktop app’s connectors don’t call your MCP server from your device. Anthropic’s documentation says the call comes from Anthropic’s cloud, and servers behind a VPN or a firewall won’t connect. Supporting them would mean a public endpoint.
We decided against that. I can drive my desktop Claude session from my phone, and that desktop session reaches the internal gateway. The exposure footprint stays at zero public endpoints, which is worth more than native mobile support.
The design #
One internal gateway is the only way in. It listens on port 443 on the LAN and our NetBird mesh, and nowhere else.
People sign in with Keycloak through OAuth 2.1 (authorization code with PKCE). The client handles the browser flow, and Keycloak issues short-lived tokens. Devices without a browser can use the device authorization grant.
Workloads such as open-webui, n8n and agents running on servers get a SPIFFE identity from SPIRE. They present a JWT-SVID, or use mTLS with an X.509-SVID.
The gateway accepts tokens from exactly two issuers, Keycloak and SPIRE. Both are signed JWTs, so the gateway validates them the same way. It then decides per caller and per tool what is allowed:
- the Vault and Kubernetes MCP servers: only me and named workloads
- Home Assistant: only the tools it needs
- write tools: people only, unless a workload is explicitly granted them
Behind the gateway, every MCP server pod accepts only the gateway’s SPIFFE identity over mTLS. Even inside the cluster, nothing else can call them.
What SPIFFE solves, and what it doesn’t #
SPIFFE was my first idea for the whole problem, so it’s worth being precise about where it fits.
It fits the workloads well. A pod gets an identity from the platform itself, with no secret to distribute. The MCP servers use that identity to log in to Vault (through Vault’s standard JWT auth method, because native SPIFFE auth is an Enterprise feature) and receive short-lived tokens with a narrow policy.
It fits people badly. SPIFFE identifies workloads, and the AI clients mostly can’t present a client certificate anyway. Keycloak already knows who the people are.
And it can’t remove credentials that the upstream API insists on:
| Upstream | Best we can do |
|---|---|
| Kubernetes | Vault’s Kubernetes secrets engine mints a service-account token per request, valid for minutes. No static kubeconfig. |
| Vault | No standing token at all |
| GitLab, Grafana | Access tokens with an expiry, rotated by Terraform |
| n8n, listmonk | Static keys in Vault, fetched at runtime by an attested pod, rotated on a schedule |
So SPIFFE turns “a token in every config file” into “a few upstream keys in Vault, only readable by the pod that needs them”. That’s a large reduction, not zero.
Why a gateway instead of auth in every server #
We run more than a dozen MCP servers from many different authors. Some support bearer tokens, some support nothing, none support SPIFFE. Patching each one would mean maintaining a dozen forks.
A gateway moves authentication, authorization, audit logging and rate limiting into one place. The MCP servers stay stock, and adding a server means adding a route and a policy. The cost is a single point of failure for all AI tooling, so the production gateway will run with two replicas.
Our first candidate is agentgateway, an MCP-aware proxy that validates JWTs and can apply rules to claims. A proof of concept has to confirm three things before we commit:
- it accepts tokens from both issuers
- it talks mTLS with SPIFFE certificates to the backends
- Keycloak’s metadata satisfies the MCP clients, which the agentgateway docs themselves warn about
If it falls short, Envoy with an external authorization service is the fallback.
What comes next #
The build runs in phases, and each one gets its own post:
- SPIRE on our non-production Talos cluster, plus the Vault login for SPIFFE identities.
- The gateway proof of concept with Keycloak, Claude Code and Codex.
- Six MCP servers moved off my Mac into their own namespace.
- Promotion to production, and moving the MCP servers that still run on Docker.
One piece is already done. SPIRE ships no macOS build, so I built and tested the agent myself. That’s the next part.
Get new posts by email
One mail when a new article goes live: what it covers and a link. No tracking pixels, unsubscribe in one click.


