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 prompts/list from configuration, expanding tools/call and resources/read into upstream http requests, and rendering prompts/get from configured message templates.

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
    prompts:
      summarize:
        description: Summarize a document about a topic
        arguments:
          - name: topic
            description: The topic to summarize
            required: true
        messages:
          - role: user
            text: "Please summarize the document about ${args.topic}."
  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
  prompts:
    summarize:
      description: Summarize a document about a topic
      arguments:
        - name: topic
          description: The topic to summarize
          required: true
      messages:
        - role: user
          text: "Please summarize the document about ${args.topic}."

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.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.

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 and matched by resources/read.

resources.uri*

string

Resource URI template surfaced by resources/list, with optional embedded capture names, such as order://{orderId}. Captured values are referenced from a route as ${params.x}.

resources.description

string

Resource description surfaced to MCP clients by resources/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.

options.prompts

object as map of named object

MCP prompts served locally by this binding. The named key is the prompt name surfaced to MCP clients by prompts/list and matched by prompts/get. A prompts/get request renders the messages locally with no upstream http request.

prompts.description

string

Prompt description surfaced to MCP clients by prompts/list.

prompts.arguments

array of object

Arguments accepted by the prompt, surfaced to MCP clients by prompts/list and supplied on prompts/get.

arguments[].name*

string

Argument name, referenced from a message template as ${args.name}.

arguments[].description

string

Argument description surfaced to MCP clients.

arguments[].required

boolean | Default: false

Whether the argument must be supplied on prompts/get.

prompts.messages*

array of object

Message templates rendered and returned by prompts/get.

messages[].role*

enum [ user, assistant ]

Role of the rendered message.

messages[].text*

string

Message text template. Supports ${args.x} interpolation, where x references a prompt argument supplied on prompts/get.

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 guarded route matches, the MCP session must be authorized for the listed roles, otherwise the stream is rejected.

routes:
  - guarded:
      my_guard:
        - pr:write

routes[].when

array of object

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

routes:
  - when:
      - tool: create_pr
      - resource: order

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.
  • ${params.x} Replaced with capture x from the matched resource uri.

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. Use a template to rename or restructure 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