Design a multi-tenant remote MCP server that exposes each customer's Postgres database. Walk through transport, auth, isolation, and observability.

Short answer·Hard·4.0 · 0·~3 min·Relevant atAnthropic Microsoft OpenAI

Attempt it

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.

Memory aid

Easy to grasp

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.

Key concepts

Multi-tenancyOAuth 2.1Rate Limiting Observability

Detailed answer & concept explanation

~9 min read

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.

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.

Cloudflare 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.
Vercel'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.
Anthropic's hosted MCP connectors enforce per-tenant rate limits and publish the JSON-RPC error -32000 plus retry_after convention for rejection responses.
Smithery tracks tool-definition hashes per server to detect post-approval mutations, addressing the rug-pull gap the protocol leaves to implementers.
Production 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?

QWalk through what happens when a tenant runs a 5 minute analytical query and the host's silent timeout is 2 minutes.

QTenant A says tenant B's queries are slowing their requests. What spans and metrics do you pull first?

QHow does the design change if tenants bring their own database credentials?

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.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.