MCP gateway overview

The MCP gateway is an HTTP filter that makes Arion itself the server side of the Model Context Protocol. 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 is enforced in one place.

How it works

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

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.
• OpenAPI sources. An OpenAPI 3.x document becomes one REST-backed tool per operation, under one namespace. See OpenAPI tools.
• 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.

Authentication happens before the gateway: place the JWT filter 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, 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 and code mode. The mode decides how agents use the registry, not what is in it:

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 or code mode. Declare your first tool in tools and REST backends, or follow the end-to-end MCP gateway guide. The full field tables are in the filter reference.