---
title: Gateways
description: Combine several MCP deployments behind one stable endpoint, with shared auth and optional tool-search.
---

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.

```text
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](#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

1. Sign in to [mcplambda.io](https://mcplambda.io) and open **Gateways**.
2. Choose **Create a Gateway** and give it a name (for example `agent-tools`).
3. Pick the deployments to combine. Servers that are stopped, or already in another Gateway, are shown as unavailable.
4. Choose an [authentication mode](#authentication).
5. Optionally enable the [tool optimizer](#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](/docs/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`.

```bash
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](/docs/cli/#gateways).

---

## MCPLambda MCP server

From an AI client connected to the [MCPLambda MCP server](/docs/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.

---

## Next steps

<Cards>
  <Card
    title="Connecting AI Clients"
    href="/docs/ai-clients/"
    description="Point Claude, Cursor, or any MCP client at your Gateway URL."
  />
  <Card
    title="The mcpl CLI"
    href="/docs/cli/#gateways"
    description="Full gateway command and flag reference."
  />
  <Card
    title="Deployment Strategies"
    href="/docs/deployment-strategies/"
    description="Get servers running before you combine them."
  />
  <Card
    title="Patterns and Use Cases"
    href="https://mcplambda.io/learn/mcplambda-gateways-patterns-and-use-cases"
    description="Auth patterns, rollout checklist, and production examples."
  />
</Cards>