Gateways | MCPLambda Docs

A Gateway puts one MCP endpoint in front of several running deployments. Your AI client connects to a single URL and sees the tools of every server behind it. You add or remove servers later without touching client config.

https://<gateway-subdomain>.mcplambda.io/mcp

Gateway subdomains use the <modifier>-<noun>-<digits>-gateway form — for example small-stone-0834-gateway. The subdomain is generated independently of the Gateway name and stays stable for the Gateway’s lifetime, so a rename never breaks a connected client.

When to use one

Situation	Use
One server, one client	Deploy it and connect directly — no Gateway needed
Several servers your agent needs together	Gateway — one URL, one auth setup
Servers that change over time	Gateway — swap members without reconfiguring clients
Many tools crowding the agent’s context	Gateway + tool optimizer

A Gateway does not replace your deployments; it points at them. Deleting a Gateway leaves its members running, and stopping one leaves them running too.

Requirements and limits

Member deployments must:

be owned by you and live in the same project as the Gateway,
be running at the time you attach them,
belong to at most one Gateway at a time.

A Gateway accepts at most 20 members. Gateway names follow DNS-1123 rules: lowercase letters, numbers, and hyphens, starting and ending with a letter or number, 63 characters max.

In the dashboard

Sign in to mcplambda.io and open Gateways.
Choose Create a Gateway and give it a name (for example agent-tools).
Pick the deployments to combine. Servers that are stopped, or already in another Gateway, are shown as unavailable.
Choose an authentication mode.
Optionally enable the tool optimizer.

The Gateway provisions and moves to running. Copy its URL from the list and hand it to any MCP client — see Connecting AI Clients.

Member changes take effect by restarting the Gateway process, because the aggregated tool index is built once at startup. Adding, removing, stopping, or restarting a member briefly rolls the Gateway; connected clients reconnect.

Authentication

Auth is enforced at the edge, in front of the Gateway. Choose it at creation and change it later without losing the URL or certificate.

Mode	Behavior
`oauth`	Default. OAuth discovery at the Gateway endpoint; clients run the standard flow
`key`	A single API key, sent by the client. Requires a lifetime (30 / 60 / 90 days or 1 year in the dashboard)
`none`	No edge authentication — anyone with the URL can call it

With key, the plaintext key is shown once at creation. Store it then; it cannot be retrieved afterwards, only rotated.

Tool names

Aggregated tools are exposed with the member workload name as a prefix — <workload>_<tool> — so two servers that both expose search do not collide.

Tool optimizer

A Gateway that aggregates many servers pushes every tool schema into your agent’s context window. With the tool optimizer on, the Gateway stops advertising the full list and advertises two meta-tools instead:

find_tool — hybrid keyword + semantic search over the aggregated tools
call_tool — dynamic dispatch to whatever find_tool returned

The agent searches for what it needs instead of reading everything up front. It is off by default and opt-in per Gateway.

Setting	Default	Range
Results returned by `find_tool`	`8`	1–50
Search blend (keyword ↔ semantic)	`0.5`	`0.0` all keyword to `1.0` all semantic
Semantic distance cutoff	`1.0`	`0` identical to `2` unrelated

Before you turn it on

Tools are no longer individually callable. The Gateway answers tools/call for find_tool and call_tool only; every other name returns tool not found. A client with a hardcoded tool name, a pinned allowlist, or a saved agent config referencing <workload>_<tool> breaks until it routes through find_tool first. Agents that discover tools dynamically are unaffected.
The Gateway serves MCP 2025-11-25 to every client while the optimizer is on, including clients that support the newer revision. Gateways without the optimizer keep full support for both.
Changing optimizer settings restarts the Gateway, so connected clients reconnect.

Nothing is destroyed by enabling it — members, subdomain, auth mode, and the member deployments are untouched, and turning it back off restores the full tool list.

The suggestion hint

The dashboard and mcpl gateway list flag a Gateway once it has served 25 or more distinct tools recently. That is a usage signal drawn from actual tool invocations, not from the full inventory, so a Gateway with no traffic reports zero. It is advisory — nothing acts on it automatically.

Below roughly that many tools, the two meta-tools plus a search round-trip usually cost more context than they save.

Status

Status	Meaning
`provisioning`	Being created
`running`	Serving traffic
`degraded`	Serving, but one or more backends are unhealthy
`stopped`	Stopped; member deployments still running
`failed`	Provisioning or runtime failure — see the error message

A transient failure is reconciled rather than becoming sticky: the Gateway returns to running once its backends recover.

CLI

The same lifecycle is available from the terminal. Every subcommand except create takes the Gateway UUID from mcpl gateway list.

mcpl gateway create agent-tools --member <deployment-uuid> --member <deployment-uuid>
mcpl gateway list
mcpl gateway add-member <gateway-id> <deployment-uuid>
mcpl gateway update <gateway-id> --optimizer
mcpl gateway stop <gateway-id>
mcpl gateway delete <gateway-id>

Full flags, defaults, and the rest of the subcommands are in the mcpl CLI reference.

MCPLambda MCP server

From an AI client connected to the MCPLambda MCP server, agents can manage Gateways directly:

Tool	Description
`list_gateways`	List Gateways in a project
`create_gateway`	Create a Gateway from existing deployments
`update_gateway`	Change name, auth, or optimizer settings
`add_gateway_member`	Attach a running deployment
`remove_gateway_member`	Detach a deployment without deleting it

These reuse the same deployment read/write scopes as the REST API.

Deleting

Deleting a Gateway removes the endpoint and revokes any Gateway API key. Member deployments are left running and are free to join another Gateway.

Deleting a project is destructive and cascades: its Gateways are torn down before its deployments are deleted.