Skip to main content

mcp-http proxy

mcp-http proxy

The mcp-http proxy binding accepts mcp streams and produces http streams, terminating tools/list, resources/list, and resources/templates/list from configuration, and expanding tools/call and resources/read into upstream http requests.

mcp_http_proxy:
  type: mcp-http
  kind: proxy
  options:
    authorization:
      my_guard:
        credentials:
          headers:
            authorization: Bearer {credentials}
    tools:
      create_pr:
        description: Create a pull request to merge one branch into another.
        summary: "Created pull request #${result.number}"
        schemas:
          input:
            model: json
            catalog:
              my_catalog:
                - subject: create_pr_params
                  version: latest
          output:
            model: json
            catalog:
              my_catalog:
                - subject: create_pr_result
                  version: latest
    resources:
      order:
        uri: "order://{orderId}"
        description: Customer order by identifier
        mimeType: application/json
        schemas:
          output:
            model: json
            catalog:
              my_catalog:
                - subject: order_result
                  version: latest
  routes:
    - when:
        - tool: create_pr
      exit: http_client
      with:
        headers:
          ":method": POST
          ":scheme": https
          ":authority": api.github.com
          ":path": /repos/${args.owner}/${args.repo}/pulls
        body:
          model: json
          catalog:
            my_catalog:
              - subject: create_pr_body
                version: latest
    - when:
        - resource: order
      exit: http_client
      with:
        headers:
          ":method": GET
          ":scheme": https
          ":authority": api.orders.internal
          ":path": /orders/${params.orderId}

Configuration (* required)

options

object

The mcp-http specific options.

options:
  authorization:
    my_guard:
      credentials:
        headers:
          authorization: Bearer {credentials}
  tools:
    create_pr:
      description: Create a pull request to merge one branch into another.
      summary: "Created pull request #${result.number}"
      schemas:
        input:
          model: json
          catalog:
            my_catalog:
              - subject: create_pr_params
                version: latest
        output:
          model: json
          catalog:
            my_catalog:
              - subject: create_pr_result
                version: latest
  resources:
    order:
      uri: "order://{orderId}"
      description: Customer order by identifier
      mimeType: application/json
      schemas:
        output:
          model: json
          catalog:
            my_catalog:
              - subject: order_result
                version: latest

options.authorization

object as map of named object

Guard credentials to inject into the upstream http request. The named key references a guard defined elsewhere in the configuration. At most one guard may be referenced.

authorization.credentials

object

Credentials derived from the named guard.

credentials.headers

object as map of named string

HTTP request headers added to the upstream request, with values resolved from the guarded session.

  • {credentials} Replaced with the raw credentials presented to the named guard.
  • {identity} Replaced with the authorized identity resolved by the named guard.

options.tools

object as map of named object

MCP tools terminated by this binding and expanded into http requests. The named key is the tool name surfaced to MCP clients by tools/list and matched by tools/call.

tools.title

string

Tool title surfaced to MCP clients by tools/list. Unlike tools.description, there is no fallback — a tool with no authored title has none.

tools.description

string

Tool description surfaced to MCP clients by tools/list.

tools.summary

string

Result summary template surfaced as the tool-call text result. Supports ${result.x} interpolation, where x references a property of the upstream JSON response.

tools.schemas*

object

JSON schema converters for the tool.

schemas.input*

object

Converter validating the tools/call arguments before the upstream http request is dispatched. A converter binds a model to a registered catalog subject.

input.model*

string

Model name used to convert and validate the value, such as json.

input.catalog

object as map of named array

Catalog subjects resolving the schema used for validation.

catalog[].subject*

string

Subject name identifying the schema in the named catalog.

catalog[].version

string | Default: latest

Specific version of the registered schema.

schemas.output

object

Converter validating and projecting the upstream http response, surfaced as the tool-call structuredContent. Uses the same shape as schemas.input.

tools.annotations

object

Behavior hints surfaced to MCP clients by tools/list. Unlike mcp-openapi's tools.annotations, there is no HTTP-method-derived default — a hint left unset here is simply absent. Each hint resolves independently — overriding one does not require overriding the others.

annotations:
  readOnlyHint: false
  destructiveHint: false
  idempotentHint: false

annotations.readOnlyHint

boolean

Whether the tool only reads data without modifying any state.

annotations.destructiveHint

boolean

Whether the tool may perform a destructive update.

annotations.idempotentHint

boolean

Whether calling the tool repeatedly with the same arguments has no additional effect beyond the first call.

annotations.openWorldHint

boolean

Whether the tool interacts with an open-ended set of external entities, rather than a fixed, closed set.

options.resources

object as map of named object

MCP resources terminated by this binding and expanded into http requests. The named key is the resource name surfaced to MCP clients by resources/list or resources/templates/list, and matched by resources/read.

resources.uri*

string

Resource URI, with optional embedded capture names, such as order://{orderId}. A URI with no captures is a concrete resource surfaced by resources/list; a URI with one or more captures is a resource template surfaced by resources/templates/list instead. Captured values are referenced from a route as ${params.x}.

resources.description

string

Resource description surfaced to MCP clients by resources/list or resources/templates/list.

resources.mimeType

string

MIME type of the resource contents surfaced to MCP clients.

resources.schemas

object

JSON schema converter for the resource.

schemas.output

object

Converter validating and projecting the upstream http response, surfaced as the resource contents. Uses the same shape as schemas.input.

routes

array of object

Conditional mcp-http specific routes, resolving the upstream http request for a matched tools/call or resources/read.

routes:
  - when:
      - tool: create_pr
    exit: http_client
    with:
      headers:
        ":method": POST
        ":scheme": https
        ":authority": api.github.com
        ":path": /repos/${args.owner}/${args.repo}/pulls
      body:
        model: json
        catalog:
          my_catalog:
            - subject: create_pr_body
              version: latest
  - when:
      - resource: order
    exit: http_client
    with:
      headers:
        ":method": GET
        ":scheme": https
        ":authority": api.orders.internal
        ":path": /orders/${params.orderId}

routes[].guarded

object as map of named array of string

Roles required by the named guard. When a route with with matches, the MCP session must be authorized for the listed roles on every applicable route, otherwise the stream is rejected.

A route may omit both when and with to act as a guard-only layer, applying its guarded roles globally across every tool and resource rather than mapping to an upstream request. Combine a global guard-only layer with a route-specific one by giving the guard-only layer a single when condition instead of omitting when. Roles from every applicable layer — the matched mapping route plus any global or scoped guard-only layers — must all authorize.

routes:
  - guarded:
      my_guard:
        - read
  - when:
      - tool: create_pr
    exit: http_client
    guarded:
      my_guard:
        - pr:write
    with:
      headers:
        ":method": POST
        ":scheme": https
        ":authority": api.github.com
        ":path": /repos/${args.owner}/${args.repo}/pulls

routes[].when

array of object

At most one condition to match this route. A route with with requires exactly one when condition, mapping one tool or resource to an upstream request; a route without with may omit when entirely to guard every tool and resource, or give exactly one condition to scope the guard to a single tool or resource. Read more: When a route matches

routes:
  - when:
      - tool: create_pr

Each condition specifies exactly one of tool or resource, never both.

when[].tool

string

Tool name to match, referencing an entry in options.tools.

when[].resource

string

Resource name to match, referencing an entry in options.resources.

routes[].with

object

Resolves the upstream http request for the matched route.

with:
  headers:
    ":method": POST
    ":scheme": https
    ":authority": api.github.com
    ":path": /repos/${args.owner}/${args.repo}/pulls
  body:
    model: json
    catalog:
      my_catalog:
        - subject: create_pr_body
          version: latest

with.headers*

object as map of named string

HTTP request headers for the upstream request, including the pseudo-headers :method, :scheme, :authority, and :path. Values support interpolation.

  • ${args.x} Replaced with property x of the tools/call arguments. x may be dotted to reference a nested property, such as ${args.repository.owner}.
  • ${params.x} Replaced with capture x from the matched resource uri.

Every header other than :path is omitted from the upstream request entirely when a referenced property or capture is absent, rather than being sent with an empty value.

The :path pseudo-header resolves differently: a referenced property or capture that is absent resolves to an empty string rather than omitting the header, since :path is always required. To omit an individual query parameter instead, mark its fragment as optional with ${?args.x=name} (or ${?params.x=name}) in place of a literal name=${args.x} pair — the whole name=value fragment, including its separator, is dropped when x is absent.

with:
  headers:
    ":method": GET
    ":scheme": https
    ":authority": api.github.com
    ":path": /items?q=${args.q}&${?args.limit=limit}

with.cookies

object as map of named string

Cookie name/value pairs aggregated into a single Cookie header on the upstream request. Values support the same ${args.x} and ${params.x} interpolation as with.headers. A cookie whose referenced property or capture is absent is dropped from the aggregate on its own; the Cookie header itself is omitted only when every configured cookie is absent.

with:
  cookies:
    session: ${args.sessionId}
    locale: ${params.locale}

with.query

object

Converter projecting the tools/call arguments onto the upstream request query string. A converter binds a model to a registered catalog subject. Properties present in the resolved schema are emitted as query parameters; absent optionals are omitted.

with.body

object

Upstream http request body, defined either as a converter projection or as an explicit template.

A converter projects the tools/call arguments onto the request body, pruned to the properties in the resolved schema, with absent optionals omitted.

with:
  body:
    model: json
    catalog:
      my_catalog:
        - subject: create_pr_body
          version: latest

body.template

object as map of named string

Explicit request body, mapping each body property to an interpolated value. Supports ${args.x} interpolation, where x references a property of the tools/call arguments; x may be dotted to reference a nested property, such as ${args.pr.branch}. Use a template to rename or restructure arguments, including flattening nested arguments, before dispatch.

with:
  body:
    template:
      title: ${args.title}
      head: ${args.branch}
      base: ${args.target}

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