Every MCP server you run has its own URL, and every client entry is one more thing to configure, secure, and keep updated. Worse, MCP clients typically load the full tool list of every connected server into the model’s context — ten servers with twenty tools each means two hundred schemas competing for attention before the agent does any work (the official client best practices call this out and recommend progressive discovery).
An MCPLambda Gateway collapses that sprawl: up to 20 running deployments in a project behind one stable MCP endpoint, with authentication at the boundary and an optional tool optimizer for large catalogs. The Gateways overview covers the product story; this guide goes deeper — how it actually behaves, which auth mode to pick, when the optimizer is worth its trade-offs, and the use cases it unlocks.
What an MCPLambda Gateway actually is
┌──────────────┐ one stable URL (Streamable HTTP)
│ MCP client │ ───────────────────────────────────┐
│ Claude, IDE, │ ▼
│ your agent │ ┌────────────────────────────────┐
└──────────────┘ │ MCPLambda Gateway │
│ · boundary auth (OAuth | key) │
│ · merged tool list, │
│ deployment-prefixed names │
│ · optional tool optimizer │
└───────┬────────────────┬───────┘
│ tools/call fan-out
┌────────▼─────┐ ┌──────▼──────┐
│ deployment A │ │ deployment B │ … up to 20
│ (github) │ │ (jira) │
└──────────────┘ └──────────────┘
own logs · secrets · analytics · scalingThe protocol part (specification 2025-11-25): the client initializes a session over Streamable HTTP — the server MUST provide a single HTTP endpoint supporting POST and GET — discovers tools with tools/list, and invokes them with tools/call. Servers that declare the listChanged capability SHOULD send a notification when the tool list changes.
The product part (MCPLambda): membership of up to 20 running deployments in one project, a stable Gateway URL that survives membership changes, auth enforced once at the boundary, tool names automatically prefixed per deployment so identical tool names never collide, lifecycle statuses (pending → provisioning → running, plus degraded, stopped, failed), and a distinct_tool_count signal that shows real usage once traffic flows.
Two lifecycle boundaries matter in practice:
- Stopping or deleting a Gateway does nothing to its members. Each deployment keeps running with its own logs, analytics, secrets, scaling, and direct endpoint.
- Membership edits briefly reconnect the Gateway while its tool list refreshes; clients may need to reconnect to pick up the new list.
Two discovery modes: full tool list vs tool optimizer
This is the decision most Gateway guides skip, and it is the one that determines how well agents behave at scale.
Full tool list (default). Clients see every tool from every member deployment, prefixed by deployment (for example, github_create_issue next to jira_create_issue — no collisions). Simple, deterministic, and the right default while the aggregated count stays manageable.
Tool optimizer. Clients see exactly two meta-tools, find_tool and call_tool. The agent describes what it wants (“file an issue”), gets back a shortlist of matching tools, and calls through — search instead of read-everything. Three tunables (sane defaults, adjustable on the Gateway):
| Tunable | Default | Range | What it controls |
|---|---|---|---|
| Max results | 8 | 1–50 | How many tools find_tool returns per search |
| Semantic ratio | 0.5 | 0.0–1.0 | Blends keyword search (0) with semantic search (1) |
| Distance cutoff | 1.0 | 0–2 | Drops semantic matches weaker than the threshold |
When the aggregated tool count gets high enough for this to matter, the dashboard flags the Gateway with an optimizer suggestion — advisory only; nothing changes until you opt in.
The trade-offs, stated plainly:
| Full tool list | Tool optimizer | |
|---|---|---|
| Client sees | Every member tool, prefixed | find_tool + call_tool |
| Context cost | Grows with tool count | Flat, regardless of catalog size |
| Tool selection | Model reads every schema | Search returns a shortlist |
| Protocol revision | Whatever client and Gateway negotiate | Pinned to 2025-11-25 while enabled — clients supporting newer revisions are held on it |
| Change impact | Membership edit → brief reconnect | Saving optimizer settings restarts the Gateway |
| Best when | Tens of tools, predictable set | High tool counts, or the suggestion flag appears |
Auth at the Gateway boundary (mapped to the MCP specification)
The 2025-11-25 authorization spec treats a protected MCP server as an OAuth 2.1 resource server: clients discover the authorization server via RFC 9728 Protected Resource Metadata, tokens MUST be validated as intended for the resource they are presented to, and a server MUST NOT pass a client’s token through to upstream APIs. Gateway auth modes map onto that cleanly:
- OAuth (recommended for teams). Each user signs in from their MCP client and grants access. Per-user identity at the boundary, and it conforms to the spec’s discovery model. One scoping fact worth repeating: Gateway OAuth authenticates clients to your Gateway — it does not broker OAuth into third-party SaaS products behind the member servers.
- API key (recommended for machines). Trusted clients send one key in the
X-API-Keyheader. Keys expire — 30, 60, 90, or 365 days — and rotate from the Gateway details page. This is the fit for CI jobs, service accounts, and background agents. - Public (handle with care). Anyone with the URL can invoke every exposed tool. The transports spec says servers SHOULD implement proper authentication for all connections — choose public only when every member tool is genuinely safe for anonymous use.
One subtlety that prevents confused-deputy bugs: member deployments keep their own secrets and upstream credentials. Gateway auth is an added boundary in front of them, not a replacement — and by design there is no token passthrough from client to member.
Use cases (beyond the landing page)
1. A coding-agent toolbelt per team. Repository, issue tracker, docs, and CI/deploy servers as separate deployments; one Gateway URL in every developer’s client. OAuth auth. Keep the full tool list while the count is in the tens, and prefer one Gateway per team over a single org-wide catalog — agents see the tools for the job, not everything the company runs.
2. A customer-facing MCP product surface. If your product ships an MCP integration, package features as a few deployments and front them with a Gateway whose URL goes in your docs. Add deployments later without customers changing any client config. Keys are per-Gateway and expiring, so run one Gateway per tier (trial vs production) rather than sharing one key across all customers.
3. A scoped support or operations assistant. Give the agent exactly the deployments it needs — CRM reads, ticketing, status pages — behind OAuth. Nothing else in the project is reachable through that URL, and the members’ direct endpoints stay private, so the Gateway is the single governed surface.
4. Environment separation that promotes safely. A staging Gateway and a production Gateway over the same set of deployments lets you validate client behavior and tool changes against staging before users touch them — same URL shape, different blast radius.
5. A large catalog with progressive discovery. Fifteen to twenty deployments can mean well over a hundred tools. At that point enable the optimizer (or wait for the suggestion flag): agents search with find_tool instead of ingesting every schema, and context stays flat as you add deployments.
Rollout checklist
- Deploy each server as its own deployment — independent logs, secrets, analytics, scaling
- Create the Gateway with up to 20 running members from one project
- Pick auth deliberately: OAuth for humans, expiring API key for machines, public only for provably safe tools
- Connect one client to the Gateway URL, run
tools/list, and spot-call a tool end to end - After membership changes, reconnect clients so they re-discover the tool list
- Enable the optimizer when the suggestion appears — knowing it restarts the Gateway and pins the 2025-11-25 revision
- Schedule API-key rotation (30–365 day lifetimes) and watch per-deployment tool analytics for errors
- Name an owner for the Gateway and for each member deployment
What breaks in production
| Failure | Likely cause | Fix |
|---|---|---|
| Anonymous access to destructive tools | Public auth chosen for convenience | OAuth or API key; public only when every member tool is safe |
| Clients never see new or removed tools | Membership changed; clients cached the list | Reconnect clients; expect the brief Gateway reconnect on edits |
| Agent picks the wrong tool at 100+ tools | Full-list context bloat | Enable the optimizer, or split into focused Gateways per job |
| Expecting SaaS OAuth brokerage | Gateway OAuth authenticates to the Gateway only | Handle third-party OAuth upstream of the deployments |
| Bypass sprawl | Member direct endpoints shared around | Keep direct endpoints private; publish only the Gateway URL |
| Surprise protocol pin | Optimizer enabled without reading the warning | Plan client expectations around the 2025-11-25 revision while it stays on |
The bottom line
A Gateway is how you go from “a server” to “a tool surface”: one stable URL, auth at the boundary, members that stay independently deployable and observable, and progressive discovery when the catalog outgrows a full tool list. Start with the Gateways overview, then create one from the running deployments in your project.
Related guides
Gateway vs host your own · Internal tools · Auth patterns
Sources
Verified against MCP specification 2025-11-25 and in-repo MCPLambda product behavior as of 2026-08-07.
- Tools — 2025-11-25 —
tools/list,tools/call,listChanged - Transports — 2025-11-25 — single endpoint, POST + GET
- Authorization — 2025-11-25 — resource-server model, audience validation, no token passthrough
- Client best practices — progressive discovery for large toolsets
- Security best practices
- MCPLambda Gateways overview · MCPLambda docs
