Skip to main content

mcp proxy

mcp proxy

The mcp proxy binding routes inbound MCP requests to upstream MCP servers based on toolkit and per-route tool, prompt, and resource filters.

mcp_proxy:
  type: mcp
  kind: proxy
  options:
    cache:
      store: my_store
      ttl: 5m
  routes:
    - exit: app1
      when:
        - toolkit: bluesky
          tool:
            - post_*
    - exit: app2
      when:
        - toolkit: quartz

Configuration (* required)

options

object

The proxy kind mcp specific options.

options:
  cache:
    store: my_store
    ttl: 5m

options.cache

object

Cache configuration for upstream MCP responses, backed by a referenced store binding.

cache.store*

string

Name of the store binding used to persist cached entries.

cache.ttl

string | Default: PT5M

Time-to-live before a cached entry is refreshed.

cache.authorization

object as map of named object properties

Authorization by a named guard used when refreshing cached entries.

authorization.credentials

string

Credentials used by the named guard when refreshing cached entries.

cache.tools

object

Tool-related cache configuration.

object

Agent-callable tool search over cached tools. Injects three synthetic tools into tools/list responses, each answering its tools/call requests directly from the cache instead of routing to an upstream MCP server:

  • search_tools ranks cached tools by relevance to a natural-language query argument and returns name and description matches.
  • describe_tool resolves the full cached definition, including input and output schema, of a tool named exactly as returned by search_tools.
  • execute_tool invokes a tool by name exactly as tools/call would, once its schema is known via describe_tool.
tools:
  search:
    toolkit: zilla

search.toolkit

string

Optional toolkit__ prefix applied to the three synthetic tool names (search_tools, describe_tool, execute_tool), matching the naming convention used for proxied tools. When omitted, the tools are exposed unprefixed.

search.limit

integer | Default: 5

Maximum number of matching tools returned, further capped by any max_results argument in the request.

search.fields

array of enum [ name, description, output-schema ] | Default: [ name, description ]

Tool fields indexed for ranking.

search.weights

object as map of named number

Per-field weight multiplier applied to term frequency during ranking. Keys reference entries in fields.

search.type

enum [ keyword ]

Shorthand for a single ranking backend with no backend-specific fields. Mutually exclusive with index.

search:
  toolkit: zilla
  type: keyword

search.index

array of object

One or more ranking backends, fused by reciprocal rank when more than one is configured. Mutually exclusive with type.

search:
  toolkit: zilla
  index:
    - type: keyword

index[].type*

enum [ keyword ]

Ranking backend. Only keyword (BM25 ranking over the configured fields) is available.

tools.eager

object

Eager/cold partitioning of cached tools in tools/list responses, applied after per-session scope filtering. Cold tools are annotated defer_loading: true when no tool search is configured, or omitted from tools/list entirely — reachable only through search results — when one is.

tools:
  eager:
    policy: explicit
    match:
      - github__list_repos
      - "slack__*"

eager.policy

enum [ none, all, explicit ] | Default: none

Which cached tools are eager. none marks every tool eager (no partitioning is applied), all marks every tool cold, and explicit marks only tools matching match eager, leaving every other tool cold.

eager.match

array of string

Glob patterns of tool names admitted to the eager set, where * matches any sequence of characters. Required when policy is explicit; not allowed for any other policy.

options.tools

enum [ avro, boolean, double, float, int32, int64, json, string ], object

Validation model applied to tools/call request arguments. Refer to the individual model docs for type specific implementation.

routes

array of object

Conditional mcp specific routes.

routes[].guarded

object as map of named array of string

Roles required by the named guard. When a guarded route matches, drives scope-based filtering of tools/list, prompts/list, and resources/list responses, admitting only the entries the caller's roles allow.

routes:
  - guarded:
      my_jwt_guard:
        - read

routes[].when

array of object

List of conditions (any match) to match this route. Read more: When a route matches

when[].toolkit*

string

Toolkit name to match.

when[].tool

string or array of string

Glob patterns of tool names to expose, where * matches any sequence of characters. Only tools whose name matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of tool activates the tools capability for this condition; when none of tool, prompt, or resource are given, every capability is admitted.

when[].prompt

string or array of string

Glob patterns of prompt names to expose, where * matches any sequence of characters. Only prompts whose name matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of prompt activates the prompts capability for this condition.

when[].resource

string or array of string

Glob patterns of resource URIs to expose, where * matches any sequence of characters. Only resources whose URI matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of resource activates the resources capability for this condition. Applies to both resources/list and resources/templates/list.

routes[].with

object

Route with override configuration.

with.cache

object

Cache override configuration for this route.

cache.credentials

string

Credentials used by the named guard when populating the cache for this route. When omitted, falls back to options.cache.authorization's credentials.

routes[].exit

string

Next binding when following this route.

routes:
  - exit: app1
    when:
      - toolkit: bluesky
        tool:
          - post_*
    guarded:
      my_jwt_guard:
        - read
  - exit: app2
    when:
      - toolkit: quartz

exit

string

Default exit binding when no conditional routes are viable.

exit: echo_server

telemetry

object

Defines the desired telemetry for the binding.

telemetry.metrics

array

Telemetry metrics to track

telemetry:
  metrics:
    - stream.*

telemetry.attributes

object as map of named string properties

Telemetry attributes to add to the binding metrics.

Gateway Version