---
title: "MCP gateway overview"
url: "/docs/mcp-gateway/overview/"
kind: "concept"
summary: "How the MCP gateway filter turns Arion into an MCP server: one endpoint, a registry of namespaced tools, and two ways for agents to use them."
---

> Arion site index: [/llms.txt](/llms.txt)

# MCP gateway overview

How the MCP gateway filter turns Arion into an MCP server: one endpoint, a registry of namespaced tools, and two ways for agents to use them.

The MCP gateway is an HTTP filter that makes Arion itself the server side of the [Model Context Protocol](https://modelcontextprotocol.io/). Agents connect to a single `/mcp` endpoint, and Arion serves a registry of tools backed by your existing REST APIs, OpenAPI documents and MCP servers. Use it when agents need tools that live behind services you already route with Arion.

## Why it matters

Agents speak MCP; production services speak HTTP. Bridging the two usually means writing and operating a separate MCP server per API. The gateway removes that layer: one filter on a listener exposes an MCP endpoint, and the proxy dispatches each tool call itself. Tool traffic inherits everything the listener already has: TLS, JWT authentication, clusters with load balancing and health checks, access logs, metrics and tracing. Policy such as [per-tool authorization](@/docs/mcp-gateway/tool-authorization.md) is enforced in one place.

## How it works

{{ <figure src="img/docs/mcp-gateway.svg" alt="An agent posts to /mcp on Arion; the MCP gateway filter owns a tool registry with search and RBAC, and dispatches each call to a REST cluster, an upstream MCP server, or dynamically discovered servers." caption="One filter owns the tool registry and dispatches every call to its backend." label="Figure 1." /> }}

The filter sits in the HTTP filter chain before the router:

```yaml,arion=fragment
http_filters:
  - name: arion.filters.http.mcp
    typed_config:
      "@type": type.googleapis.com/arion.extensions.filters.http.mcp.mcp_gateway.v3.McpGateway
      server_info:
        name: api-tools
        version: "1.0.0"
      tools_mode: {}
  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
```

Agents talk to the gateway over MCP streamable HTTP:

- **Sessions.** A `POST /mcp` with `initialize` creates a session and returns an `mcp-session-id` response header. Every later request must send that header.
- **Headers.** Clients must accept both `application/json` and `text/event-stream`, and every answer is sent as `application/json`.
- **Other methods.** `DELETE /mcp` ends a session, and idle sessions expire after five minutes. `GET /mcp` returns method not allowed; there is no separate SSE endpoint.
- **Routing.** The gateway answers every request on its listener, so the connection manager's route config needs only a single fallback route.

The gateway supports `initialize`, `ping`, `tools/list` and `tools/call`. Every tool has a qualified name, `namespace.name`, such as `crm.find_customer`. The registry fills from four sources:

- **Static tools with a REST backend.** The call is transcoded into an HTTP request (method, templated path, query parameters, optional body) and sent straight to the tool's cluster; the gateway resolves the cluster directly rather than going through the route table. See [tools and REST backends](@/docs/mcp-gateway/tools-and-rest-backends.md).
- **OpenAPI sources.** An OpenAPI 3.x document becomes one REST-backed tool per operation, under one namespace. See [OpenAPI tools](@/docs/mcp-gateway/openapi-tools.md).
- **Static tools with an MCP server backend.** The call is forwarded to one tool of an upstream MCP server over streamable HTTP.
- **Dynamic MCP servers.** The gateway calls `tools/list` on an upstream MCP server and materializes each tool it returns under that server's namespace. See [federation](@/docs/mcp-gateway/federation.md).

Authentication happens before the gateway: place the [JWT filter](@/docs/security/jwt.md) earlier in the same chain, and the gateway's per-tool RBAC evaluates the validated claims. The registry can also grow and shrink at runtime through [TDS](@/docs/mcp-gateway/tool-discovery-tds.md), an xDS-based discovery service for tools.

## Tools mode and code mode

Each gateway runs in exactly one mode, and each mode has its own page: [tools mode](@/docs/mcp-gateway/tools-mode.md) and [code mode](@/docs/mcp-gateway/code-mode.md). The mode decides how agents use the registry, not what is in it:

| | Tools mode (`tools_mode: {}`) | Code mode (`code_mode: {...}`) |
|---|---|---|
| `tools/list` | Eager tools, plus `tool_search` when progressive tools exist | One tool, `execute` |
| How agents call tools | One `tools/call` per tool, one model turn each | A TypeScript script that calls many tools in one `execute` |
| Discovery | [`tool_search`](@/docs/mcp-gateway/tool-search.md) and `POST /mcp/search` | The script's `catalog` API and toolkits |
| Best for | Simple tasks, and clients that expect a classic tool list | Multi-step workflows and large catalogs |
| Build feature | None | `codemode` |

In both modes, every tool call lands on the same registry. The same authorization, schema validation, timeouts, size limits and metrics apply, so choosing code mode changes how tools are called, never what a caller may reach.

## Key terms

- **Tool:** a named operation with a description and a JSON Schema for its arguments, addressed by its qualified name, `namespace.name`.
- **Namespace:** the first part of a tool's name. It groups related tools, and each namespace belongs to one source: static or TDS tools, one OpenAPI source, or one dynamic server.
- **Tool registry:** the per-gateway set of tools, built from static config, OpenAPI sources, dynamic discovery and TDS.
- **Disclosure mode:** whether a tool is listed in `tools/list` (`EAGER`) or found through search (`PROGRESSIVE`, the default).
- **Mode:** `tools_mode` or `code_mode`, the surface a gateway presents to agents.
- **Toolkit:** in code mode, a named bundle of related tools with instructions for composing them.
- **Session:** the state created by `initialize` and carried in the `mcp-session-id` header; `tools/call` requires one.
- **TDS:** the Tool Discovery Service. It delivers tools, OpenAPI sources, dynamic servers and toolkits over xDS.

## Next

Continue with the mode your gateway will run: [tools mode](@/docs/mcp-gateway/tools-mode.md) or [code mode](@/docs/mcp-gateway/code-mode.md). Declare your first tool in [tools and REST backends](@/docs/mcp-gateway/tools-and-rest-backends.md), or follow the end-to-end [MCP gateway guide](@/guides/mcp/mcp-gateway.md). The full field tables are in the [filter reference](@/reference/filters/http/mcp-gateway.md).