Design a multi-tenant remote MCP server that exposes each customer's Postgres database. Walk through transport, auth, isolation, and observability.
Free · 2 AI evals / day
A multi-tenant remote MCP server that exposes each customer's Postgres database requires six tightly integrated design layers. Getting any one wrong creates a vulnerability or an operational failure.
**Transport.** Streamable HTTP. Stdio is a local subprocess transport; it cannot serve remote clients over a network. The streamable HTTP profile lets a long-running query push partial output back to the host, preventing silent connection timeouts.
**Auth.** OAuth 2.1 with PKCE for human users. The access token carries a `tenant_id` claim. Every incoming JSON-RPC request must validate the token's tenant against the tenant identifier in the URL path or header. Bearer tokens work for backend service to service calls. Tokens without a tenant claim are unsafe because a leaked token grants access to whichever tenant the attacker guesses.
**Isolation.** Per-tenant Postgres credentials paired with a per-tenant connection pool. A shared superuser using SET ROLE at runtime is dangerous because a single SQL injection lets the attacker escape to other tenants' data. Tool execution runs inside a per-tenant async context (for example, an asyncio task group bounded by a semaphore) so one slow tenant cannot monopolize the event loop.
**Rate limiting.** Token bucket keyed on (tenant_id, tool_name). On reject, return JSON-RPC error -32000 with a `retry_after` field so the host can back off cleanly instead of hammering the server.
**Observability.** Separate OpenTelemetry spans for the JSON-RPC handler and the Postgres call, both tagged with `tenant_id`, `tool_name`, and `request_id`. Per-tenant dashboards track p95 latency, error rate, and rejection rate.
**Failure modes.** Dynamic per-tenant tool descriptions break host caching of `tools/list`. Data residency requirements force regional deployment splits. Long-running tools exceed host timeouts unless the server sends streaming heartbeat chunks. Prompt injection from query results and tool-definition mutations after user approval are protocol-level gaps the server must defend against.
**Transport.** Streamable HTTP. Stdio is process-local; it cannot serve remote clients. The streamable profile lets long queries push incremental chunks, keeping the host's timeout from firing.
**Auth.** OAuth 2.1 with PKCE for humans; bearer for service to service. The access token carries a `tenant_id` claim validated on every request. Short-lived tokens with refresh rotation. Per-tool scopes (`tables:read`, `tables:write`) enforce least privilege.
**Isolation.** Per-tenant Postgres credentials with a per-tenant connection pool. Shared-superuser plus SET ROLE collapses on SQL injection. Tool execution runs in a per-tenant async context (asyncio task group plus semaphore) so one slow tenant cannot starve others.
**Rate limiting.** Token bucket keyed on (tenant_id, tool_name). Per-tool keying matters: an expensive query and a cheap metadata call need different budgets. Rejection returns JSON-RPC error -32000 with `retry_after`. Without it, hosts hammer the server.
**Observability.** Two separate OTEL spans: one for the JSON-RPC handler, one for the Postgres call. Both tagged with `tenant_id`, `tool_name`, `request_id`, latency, `isError`. Two spans let you distinguish event loop contention (handler spike, DB flat) from database contention (both spike).
**Redesign-forcing failure modes.** (1) Per-tenant tool descriptions defeat client caching of `tools/list`; pin a static superset. (2) Data residency forces regional splits. (3) Long-running tools exceed host timeouts; stream heartbeats and cancel queries on disconnect.
**Pitfalls.** Tool-definition hash mitigates rug-pull. Prompt injection from query results demands content fencing. MCP has no sandbox; defense in depth is the server's job.
Quick reference
TL;DR
Streamable HTTP, OAuth 2.1 with tenant_id claim, per-tenant DB credentials and async contexts, token-bucket rate limits per (tenant, tool), OTEL spans tagged per tenant. MCP provides none of this.
Imagine a building where many companies share one management office. Each company has its own locked room with its own key, its own water meter, and its own usage cap. The front desk checks every visitor's badge before letting them in, writes their name on a log with the company they belong to, and only lets them visit their own room. If one company starts running loud equipment that slows the elevator for everyone, the building manager notices because each floor has its own speed meter. Some situations force a remodel: one company wants a custom lobby sign that confuses the directory, another company's government says their mail must stay in a different building, and sometimes a visitor's task takes so long the front desk forgets they came in. A multi-tenant MCP server is the same building with code in place of doors and meters.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
A single-tenant local MCP server running on the same machine as the editor. Stdio is the correct transport, OAuth adds needless ceremony, and the entire multi-tenant rate-limiting and credential isolation machinery solves problems that do not exist for a single user on one machine.
An internal prototype MCP server used by a handful of trusted developers. Per-tenant pools, async contexts, and per-(tenant, tool) rate limits are premature before the tool surface itself is validated. Ship a single-tenant version first and layer multi-tenancy when production traffic justifies the complexity.
A read-only public MCP server exposing freely available data with no per-user state. There is nothing to isolate per tenant. A global rate limit, anonymous access, and a shared connection pool are sufficient; the full multi-tenant design is over-engineered for this threat model.
A stateless MCP adapter in front of an upstream service that already enforces its own per-tenant auth and isolation. Duplicating isolation at the MCP layer creates two sources of truth that drift. Pass through the upstream service's identity model instead of building a parallel one.
Quick scan · 2–4 min
Everything important, quickly.
Open by framing that MCP provides a wire protocol and discovery model, not safety. Walk six layers in order: streamable HTTP transport (why stdio fails), OAuth 2.1 with PKCE and tenant claim (why bearer alone fails), per-tenant Postgres credentials with connection pool and bounded async context (why shared superuser fails), token-bucket per (tenant, tool) returning JSON-RPC -32000 plus retry_after, two separate OTEL spans tagged tenant_id on the handler and Postgres call. Name three redesign-forcing failure modes: dynamic per-tenant tools defeating client cache, regional residency, long-running tool timeouts. Close with tool-definition hash for rug-pull defense and prompt injection fencing.
Real-world examples
Real products, models, and research that use this idea.
1Cloudflare Workers MCP runs remote servers at the edge with OAuth 2.1 auth and per-tenant isolation enforced by the Workers runtime, serving as the reference architecture for streamable HTTP deployment in 2026.
2Vercel's MCP integration ships OAuth 2.1 with PKCE as the default for human users and bearer tokens for server to server, matching the spec's resource-server design.
3Anthropic's hosted MCP connectors enforce per-tenant rate limits and publish the JSON-RPC error -32000 plus retry_after convention for rejection responses.
4Smithery tracks tool-definition hashes per server to detect post-approval mutations, addressing the rug-pull gap the protocol leaves to implementers.
5Production remote MCP servers in 2026 commonly use FastAPI plus the Python `mcp` SDK or Node frameworks plus the `@modelcontextprotocol/sdk` TypeScript package.
Interviewer follow-ups
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you handle a tenant that needs custom tool descriptions when most MCP clients aggressively cache tools/list?
Sign in or go Pro to see the approach for this follow-up.
QWalk through what happens when a tenant runs a 5 minute analytical query and the host's silent timeout is 2 minutes.
Sign in or go Pro to see the approach for this follow-up.
QTenant A says tenant B's queries are slowing their requests. What spans and metrics do you pull first?
Sign in or go Pro to see the approach for this follow-up.
QHow does the design change if tenants bring their own database credentials?
Sign in or go Pro to see the approach for this follow-up.
Don't say this
Red flags and common mistakes that signal junior thinking. Click to expand.
Most common mistake
Sharing a single Postgres superuser across tenants and scoping with SET ROLE at runtime. One SQL injection in any tool reads every tenant's data, collapsing the isolation model entirely.