MCP proxy definition

Overview

An MCP proxy definition is the configuration object that tells Tyk how to front an MCP server. It is built on the Tyk OAS API definition format (an OpenAPI 3.0.x or 3.1.x document extended with the x-tyk-api-gateway vendor extension) and adds the MCP-specific structures that allow Tyk to inspect JSON-RPC traffic and apply middleware at the method and primitive level. This page explains the structure of an MCP proxy definition, how MCP concepts (primitives, methods, operations) map to it, and which parts of the extension are specific to MCP.

If you are not familiar with Tyk OAS API definitions, read Tyk OAS first. This page focuses on the MCP-specific aspects and assumes knowledge of the base format.

Structure Overview

An MCP proxy definition has two parts that work together:

The OpenAPI specification: Describes the MCP server’s transport endpoints and, optionally, each JSON-RPC method as a documented operation. Tyk uses this to understand the API’s shape and to present it in the Developer Portal.
The x-tyk-api-gateway extension: Contains all gateway configuration: the listen path, upstream URL, authentication, and the middleware maps that govern individual tools, resources, and prompts.

The two parts share the same file or API object:

{
  "openapi": "3.0.3",
  "info": {
    "title": "Weather MCP proxy",
    "version": "2025-11-25"
  },
  "paths": { ... },
  "x-tyk-api-gateway": {
    "info": { ... },
    "server": { ... },
    "upstream": { ... },
    "middleware": { ... }
  }
}

The x-tyk-api-gateway extension has four top-level sections:

Section	What it configures
`info`	API name, active state, and internal identifier
`server`	Client-facing settings: listen path, authentication, IP access control, custom domain
`upstream`	Upstream MCP server: target URL, load balancing, upstream rate limits, mTLS
`middleware`	Request processing: global, per-method, and per-primitive middleware

The sections below explain each part and the MCP-specific patterns within them.

MCP Concepts in the Definition

Three core MCP concepts shape how you write an MCP proxy definition: primitives, JSON-RPC methods, and transport endpoints, see What is MCP?. Understanding them before reading the definition structure makes the configuration decisions much clearer. In the definition, method-level middleware goes in middleware.operations, and each primitive type has its own map: mcpTools, mcpResources, and mcpPrompts.

The OpenAPI Specification Portion

The OpenAPI specification in an MCP proxy definition documents the server’s HTTP interface. For MCP, this has a standard structure that you can treat as a template.

Transport Paths

At minimum, the paths object documents the two transport endpoints:

{
  "paths": {
    "/mcp": {
      "post": {
        "summary": "Send a JSON-RPC message",
        "operationId": "mcpTransportPost",
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "example": "2025-11-25" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JSONRPCRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response or SSE stream",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JSONRPCResponse" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "202": { "description": "Accepted (notification, no response body)" }
        }
      },
      "get": {
        "summary": "Open an SSE stream",
        "operationId": "mcpSSEGet",
        "responses": {
          "200": {
            "description": "Server-sent events stream",
            "content": {
              "text/event-stream": { "schema": { "type": "string" } }
            }
          }
        }
      }
    }
  }
}

The operationId values (mcpTransportPost, mcpSSEGet) are referenced internally by Tyk for the transport endpoints. These values are fixed; do not change them.

Method Paths

In addition to the transport paths, you can document each JSON-RPC method as a separate path. This is optional for gateway operation but makes the MCP proxy browsable in the Tyk Developer Portal:

{
  "paths": {
    "/mcp/tools/call": {
      "post": {
        "summary": "Invoke a tool",
        "operationId": "tools/callPOST",
        "x-mcp-method": "tools/call",
        ...
      }
    },
    "/mcp/resources/read": {
      "post": {
        "summary": "Read a resource",
        "operationId": "resources/readPOST",
        "x-mcp-method": "resources/read",
        ...
      }
    }
  }
}

These paths are a documentation and governance interface. They present each JSON-RPC method as a distinct, typed operation, making MCP proxies discoverable alongside REST and GraphQL APIs in your Developer Portal. The path structure (/mcp/{namespace}/{action}) and the operationId convention ({method}POST) are what tie the OpenAPI spec to the middleware.operations map in the x-tyk-api-gateway extension.

The method paths do not correspond to real HTTP endpoints. All traffic still flows through POST /mcp. The method paths exist solely for documentation, schema validation, and middleware configuration purposes.

The x-tyk-api-gateway Extension

The x-tyk-api-gateway extension contains all gateway configuration. For MCP proxies, it has the same four top-level sections as any Tyk OAS API definition, with MCP-specific content in the middleware section.

info, server, and upstream

The info, server, and upstream sections work identically to a standard Tyk OAS API definition. They configure the API’s identity, its client-facing interface, and its upstream connectivity:

{
  "x-tyk-api-gateway": {
    "info": {
      "name": "Weather MCP proxy",
      "state": { "active": true }
    },
    "server": {
      "listenPath": { "value": "/weather/", "strip": true },
      "authentication": {
        "enabled": true,
        "securitySchemes": {
          "bearerAuth": { "enabled": true }
        }
      }
    },
    "upstream": {
      "url": "https://weather-mcp.example.com"
    }
  }
}

With this configuration, clients connect to Tyk at https://my-gateway.example.com/weather/mcp. Tyk authenticates the request, applies any configured middleware, and proxies it to https://weather-mcp.example.com/mcp. Tyk serves both the POST and GET transport endpoints under the same listen path. There are no MCP-specific fields in these three sections. You configure authentication, TLS, load balancing, upstream rate limits, and all other standard gateway capabilities exactly as you would for a REST API. See Tyk OAS for the full field reference for these sections. For an MCP proxy generated directly from a Tyk-managed REST API, upstream.url holds an adapter target instead of a remote server’s url. See The upstream adapter target for what this value means and why it takes this form. The example above uses bearerAuth as the security scheme, a simple bearer token check. For full OAuth 2.1 compliance (token validation, scope enforcement, Protected Resource Metadata, and token exchange), use the oauth2 scheme instead. See MCP OAuth 2.1.

The middleware Section

The middleware section is where MCP proxy definitions diverge from standard Tyk OAS API definitions. It contains the same global block for API-wide middleware, but adds two new concepts: an operations map keyed by JSON-RPC method, and three primitive maps: mcpTools, mcpResources, and mcpPrompts. This section covers where each middleware option lives in the definition; for what each option actually does, see MCP middleware.

{
  "middleware": {
    "global": { ... },
    "operations": { ... },
    "mcpTools": { ... },
    "mcpResources": { ... },
    "mcpPrompts": { ... }
  }
}

Each is explained below.

A REST API to MCP proxy only populates mcpTools. mcpResources and mcpPrompts are unused, since a REST API has no resource or prompt primitives to expose. Its tool catalog is generated from the source API’s operations rather than hand-written. See REST API to MCP x-tyk-mcp-server extension.

global: API-Wide Middleware

Global middleware applies to every request on the API. It is configured identically to a standard Tyk OAS API (CORS, traffic logs, header transformations, custom plugins, and so on). There is nothing MCP-specific here.

operations: Method-Level Middleware

The operations map lets you configure middleware that applies to every invocation of a JSON-RPC method, regardless of which specific primitive is targeted. It is keyed by the operation ID of the method path in the OpenAPI spec, which follows the convention {json-rpc-method}{HTTP-method}:

JSON-RPC method	Operation ID key
`tools/call`	`tools/callPOST`
`tools/list`	`tools/listPOST`
`resources/read`	`resources/readPOST`
`resources/list`	`resources/listPOST`
`prompts/get`	`prompts/getPOST`
`prompts/list`	`prompts/listPOST`
`initialize`	`initializePOST`

For an example, see Operation middleware.

mcpTools: Per-Tool Middleware

The mcpTools map configures middleware for individual tools. Each key is the tool name as it appears in the params.name field of a tools/call request:

{
  "middleware": {
    "mcpTools": {
      "get-weather": {
        "allow": { "enabled": true },
        "rateLimit": { "enabled": true, "rate": 100, "per": 60 }
      },
      "execute-query": {
        "allow": { "enabled": true },
        "requestSizeLimit": { "enabled": true, "value": 8192 }
      }
    }
  }
}

For how allow and block work, including allowlist mode, see Access control.

mcpResources: Per-Resource Middleware

The mcpResources map configures middleware for individual resources or URI patterns. Each key is matched against the params.uri field of a resources/read request. Keys can be exact URIs or wildcard patterns using *:

{
  "middleware": {
    "mcpResources": {
      "weather://stations/london": {
        "allow": { "enabled": true },
        "rateLimit": { "enabled": true, "rate": 100, "per": 60 }
      },
      "weather://stations/*": {
        "allow": { "enabled": true },
        "rateLimit": { "enabled": true, "rate": 20, "per": 60 }
      }
    }
  }
}

Tyk resolves matches in priority order: exact matches take precedence over wildcard matches. When multiple wildcard patterns match, the longest matching prefix wins.

mcpPrompts: Per-Prompt Middleware

The mcpPrompts map configures middleware for individual prompts. Each key is the prompt name as it appears in the params.name field of a prompts/get request:

{
  "middleware": {
    "mcpPrompts": {
      "weather-summary": {
        "allow": { "enabled": true }
      },
      "weather-alert": {
        "allow": { "enabled": true },
        "transformRequestHeaders": {
          "enabled": true,
          "add": [{ "name": "X-Prompt-Tier", "value": "premium" }]
        }
      }
    }
  }
}

REST API to MCP x-tyk-mcp-server Extension

An MCP proxy generated directly from a Tyk-managed REST API has one further structure: x-tyk-mcp-server, a vendor extension alongside x-tyk-api-gateway rather than nested inside it, holding the tool catalog Tyk derives from the source API’s OpenAPI operations. See REST API to MCP x-tyk-mcp-server extension for the full field reference, the allow-list selection rule, tool name validation limits, and worked examples.

Middleware Precedence

Tyk runs global middleware, then operation middleware, then primitive middleware. For details, see Evaluation order. All three middleware levels apply to all consumers of the proxy. For per-consumer control, use security policies. See Policies versus middleware.

A Complete Example

The following definition configures a weather MCP proxy with bearer token authentication, method-level and tool-level rate limiting, and allowlists for tools, resources, and prompts.

{
  "openapi": "3.0.3",
  "info": {
    "title": "Weather MCP proxy",
    "version": "2025-11-25"
  },
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcpTransportPost",
        "summary": "Send a JSON-RPC message",
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object" } } }
        },
        "responses": {
          "200": { "description": "JSON-RPC response or SSE stream" }
        }
      },
      "get": {
        "operationId": "mcpSSEGet",
        "summary": "Open an SSE stream",
        "responses": {
          "200": { "description": "Server-sent events stream" }
        }
      }
    }
  },
  "x-tyk-api-gateway": {
    "info": {
      "name": "Weather MCP proxy",
      "state": { "active": true }
    },
    "server": {
      "listenPath": { "value": "/weather/", "strip": true },
      "authentication": {
        "enabled": true,
        "securitySchemes": {
          "bearerAuth": { "enabled": true }
        }
      }
    },
    "upstream": {
      "url": "https://weather-mcp.example.com"
    },
    "middleware": {
      "global": {
        "trafficLogs": { "enabled": true }
      },
      "operations": {
        "tools/callPOST": {
          "rateLimit": { "enabled": true, "rate": 500, "per": 60 }
        }
      },
      "mcpTools": {
        "get-weather": {
          "allow": { "enabled": true },
          "rateLimit": { "enabled": true, "rate": 100, "per": 60 }
        },
        "get-forecast": {
          "allow": { "enabled": true },
          "rateLimit": { "enabled": true, "rate": 50, "per": 60 }
        }
      },
      "mcpResources": {
        "weather://stations/*": {
          "allow": { "enabled": true }
        }
      },
      "mcpPrompts": {
        "weather-summary": {
          "allow": { "enabled": true }
        }
      }
    }
  }
}

What this definition does:

The API listens on /weather/ and proxies to https://weather-mcp.example.com. Clients connect to {gateway_host}/weather/mcp.
Bearer token authentication is required on all requests.
All tools/call requests are rate limited to 500 per minute at the method level.
Only two tools are accessible (get-weather and get-forecast). Any other tool name is rejected. Each tool has its own tighter rate limit.
Resources matching weather://stations/* are accessible.
Only the weather-summary prompt is accessible.
Traffic logs are enabled for all requests.

This example uses bearerAuth for simplicity. For full OAuth 2.1 compliance, including token validation against an external IdP, per-primitive scope enforcement, Protected Resource Metadata, and RFC 8693 token exchange, replace bearerAuth with the oauth2 scheme. See MCP OAuth 2.1 for a complete worked example.

Supported MCP Spec Features

The following table documents which MCP protocol capabilities Tyk currently implements and how each maps to the proxy definition.

Capability	MCP spec version introduced	Tyk support	Notes
Tools (`tools/list`, `tools/call`)	Pre-2025-03-26	✅ Full	Per-tool middleware via `mcpTools`. Tool-level access control, rate limiting, timeouts, circuit breakers.
Resources (`resources/list`, `resources/read`)	Pre-2025-03-26	✅ Full	Per-resource middleware via `mcpResources`. URI wildcard patterns supported.
Prompts (`prompts/list`, `prompts/get`)	Pre-2025-03-26	✅ Full	Per-prompt middleware via `mcpPrompts`.
Streamable HTTP transport (`POST /mcp`, `GET /mcp`)	2025-03-26	✅ Full	The only supported transport. See Transport.
Legacy HTTP+SSE transport (separate POST and `/sse` endpoints)	Pre-2025-03-26	❌ Not supported	Replaced by Streamable HTTP in the MCP specification.
Sampling (`sampling/createMessage`)	Pre-2025-03-26	✅ Pass-through	Tyk proxies sampling messages. Method-level middleware via `operations` applies; primitive-level middleware does not (sampling is client-side).
Roots (`roots/list`)	Pre-2025-03-26	✅ Pass-through	Tyk proxies roots messages unchanged.
Elicitation (`elicitation/create`)	2025-03-26	✅ Pass-through	Tyk proxies elicitation messages unchanged.
Protected Resource Metadata (PRM)	2025-03-26	✅ Full	Tyk serves `/.well-known/oauth-protected-resource` automatically. Configured under `authentication.securitySchemes[name].oauth2.protectedResourceMetadata` from Tyk 5.14.0. See OAuth 2.1 authentication.
stdio transport	Pre-2025-03-26	❌ Not supported	Tyk is a network-based gateway. Use a stdio-to-HTTP bridge for local MCP servers.

MCP specification version: Tyk implements the 2025-11-25 revision of the MCP specification.

Summary

Concept	Where it lives in the definition
MCP primitives (tools, resources, prompts)	`middleware.mcpTools`, `middleware.mcpResources`, `middleware.mcpPrompts`
JSON-RPC method middleware	`middleware.operations`: keyed by `{method}POST`
API-wide middleware	`middleware.global`
Transport endpoints (`POST /mcp`, `GET /mcp`)	`paths./mcp.post`, `paths./mcp.get` in the OpenAPI spec
Listen path, authentication, upstream URL	`x-tyk-api-gateway.server`, `x-tyk-api-gateway.upstream`
API to MCP tool catalog and overrides	`x-tyk-mcp-server` (REST API to MCP proxies only)

Overview

MCP Gateway

AI Studio

Overview

Structure Overview

MCP Concepts in the Definition

The OpenAPI Specification Portion

Transport Paths

Method Paths

The x-tyk-api-gateway Extension

info, server, and upstream

The middleware Section

global: API-Wide Middleware

operations: Method-Level Middleware

mcpTools: Per-Tool Middleware

mcpResources: Per-Resource Middleware

mcpPrompts: Per-Prompt Middleware

REST API to MCP x-tyk-mcp-server Extension

Middleware Precedence

A Complete Example

Supported MCP Spec Features

Summary

​Overview

​Structure Overview

​MCP Concepts in the Definition

​The OpenAPI Specification Portion

​Transport Paths

​Method Paths

​The x-tyk-api-gateway Extension

​info, server, and upstream

​The middleware Section

​global: API-Wide Middleware

​operations: Method-Level Middleware

​mcpTools: Per-Tool Middleware

​mcpResources: Per-Resource Middleware

​mcpPrompts: Per-Prompt Middleware

​REST API to MCP x-tyk-mcp-server Extension

​Middleware Precedence

​A Complete Example

​Supported MCP Spec Features

​Summary

Overview

Structure Overview

MCP Concepts in the Definition

The OpenAPI Specification Portion

Transport Paths

Method Paths

The x-tyk-api-gateway Extension

info, server, and upstream

The middleware Section

global: API-Wide Middleware

operations: Method-Level Middleware

mcpTools: Per-Tool Middleware

mcpResources: Per-Resource Middleware

mcpPrompts: Per-Prompt Middleware

REST API to MCP x-tyk-mcp-server Extension

Middleware Precedence

A Complete Example

Supported MCP Spec Features

Summary