MCP gateway

What it does

The MCP gateway is an Arion extension that answers Model Context Protocol traffic over streamable HTTP on /mcp and owns a registry of namespaced tools. Tools come from static REST or MCP backends, from OpenAPI documents and from dynamic MCP servers, and TDS streams more over xDS. In tools mode agents list and call the tools directly. In code mode they send scripts to a single execute tool. The overview explains the moving parts; this page is the field reference.

Minimal configuration

This fragment is an entry in http_filters, before the router:

- name: arion.filters.http.mcp
  typed_config:
    "@type": type.googleapis.com/arion.extensions.filters.http.mcp.mcp_gateway.v3.McpGateway
    server_info:
      name: arion-mcp-gateway
      version: "1.0.0"
    tools_mode: {}
    tools:
      - namespace: weather
        name: get_forecast
        description: Get the weather forecast for a city
        disclosure_mode: EAGER
        input_schema:
          inline_string: >-
            {
              "type": "object",
              "properties": { "city": { "type": "string" }, "days": { "type": "integer" } },
              "required": ["city"]
            }
        rest_backend:
          cluster: weather_api
          method: GET
          path: "/v1/forecast/{{city | encode_path_segment}}"
          query_params:
            - name: days
              source: days

Top-level fields

What belongs to which mode

The registry and its sources are shared between the modes; the mode decides the surface agents see. When a field matters in only one mode, this table and the notes in each section say so.

tool_search arguments

In tools mode, tool_search is served automatically when the caller has at least one permitted progressive tool. It takes:

It returns the best-matching progressive tools as full MCP definitions (name, description, inputSchema, outputSchema) in the result's text content. POST /mcp/search takes the same three arguments as its JSON body. In code mode, the counterpart is catalog.tools.search in the SDK reference.

Tools

Every tool is addressed by its qualified name, namespace.name. That name appears in tools/list, in tools/call, in code-mode scripts and in metrics. Each advertised tool also carries _meta: {"arion/namespace": "<namespace>"}.

REST backend

See tools and REST backends for the transcoding rules.

MCP server backend

OpenAPI tool sources

Each entry expands an OpenAPI 3.x document into one REST-backed tool per operation, named {namespace}.{operationId}, when the configuration loads. See OpenAPI tools for the mapping rules.

Dynamic MCP servers

Each entry is polled with tools/list, and every discovered tool joins the registry as {namespace}.{upstream tool name}.

Tool RBAC

rbac guards tool calls and hides unauthorized tools from listing, search and the code-mode catalog. It uses the JWT validated by JWT authentication; details are in tool authorization.

Search

search tunes how tool_search, POST /mcp/search and the code-mode catalog.tools.search rank tools; see tool search.

Code mode

requires: codemode

code_mode replaces the tool list with the single execute tool. A binary built without the codemode feature rejects it. Numeric fields left at 0 take their defaults. The script API and the full list of limits are in the code mode SDK reference.

Toolkits

A toolkit appears in the execute description and in catalog.toolkits only for callers who may use every tool it names.

Endpoints

Ordering and interactions

Place the filter after CORS and after JWT authentication, because tool RBAC needs the validated claims, and before the router. Tool calls dispatch to their configured clusters, and the route table handles only requests the filter does not, so a plain fallback route is enough. TDS resources arrive as {server_info.name}/{config_name}/{resource_name}; see TDS resources. Tool invocations, including every call a code-mode script makes, are counted in the mcp_* metrics under the qualified tool name.