> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP proxy definition

> Structure of a Tyk MCP proxy definition: the OpenAPI document, MCP primitives and JSON-RPC methods, and the x-tyk-api-gateway and x-tyk-mcp-server extensions.

## 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](https://tyk.io/docs/api-management/gateway-config-tyk-oas.md)** 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.

> [!NOTE]
>
> If you are not familiar with Tyk OAS API definitions, read [Tyk OAS](https://tyk.io/docs/api-management/gateway-config-tyk-oas.md) 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:

```json theme={null}
{
  "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?](https://tyk.io/docs/ai-management/mcp-gateway/core-concepts.md#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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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. `2026-07-28` clients use `POST` only.

These sections have one MCP-specific field: `server.mcp`. Its `trustedOrigins` setting lists the browser origins Tyk trusts (see [Origin Validation](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md#origin-validation)), and its `oauthBroker` setting enables the OAuth broker (see [OAuth Broker](https://tyk.io/docs/api-management/authentication/oauth2-authentication.md#oauth-broker)). Everything else, such as authentication, TLS, load balancing and upstream rate limits, works exactly as it does for a REST API. See [Tyk OAS](https://tyk.io/docs/api-management/gateway-config-tyk-oas.md) for the full field reference for these sections.

For an MCP proxy [generated directly from a Tyk-managed REST API](https://tyk.io/docs/ai-management/mcps/api-to-mcp.md), `upstream.url` holds an adapter target instead of a remote server's url. See [The upstream adapter target](https://tyk.io/docs/ai-management/mcp-gateway/api-to-mcp-definitions.md#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](https://tyk.io/docs/ai-management/mcp-gateway/oauth-2-1.md).

### 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](https://tyk.io/docs/ai-management/mcp-gateway/mcp-middleware.md).

```json theme={null}
{
  "middleware": {
    "global": { ... },
    "operations": { ... },
    "mcpTools": { ... },
    "mcpResources": { ... },
    "mcpPrompts": { ... }
  }
}
```

Each is explained below.

> [!NOTE]
>
> 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](https://tyk.io/docs/ai-management/mcp-gateway/api-to-mcp-definitions.md).

#### 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](https://tyk.io/docs/ai-management/mcp-gateway/core-concepts.md#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:

```json theme={null}
{
  "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](https://tyk.io/docs/ai-management/mcp-gateway/mcp-middleware.md#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 `*`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://tyk.io/docs/ai-management/mcps/api-to-mcp.md) 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](https://tyk.io/docs/ai-management/mcp-gateway/api-to-mcp-definitions.md) 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](https://tyk.io/docs/ai-management/mcp-gateway/core-concepts.md#evaluation-order).

All three middleware levels apply to all consumers of the proxy. For per-consumer control, use security policies. See [Policies versus middleware](https://tyk.io/docs/ai-management/mcp-gateway/core-concepts.md#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.

```json theme={null}
{
  "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](https://tyk.io/docs/ai-management/mcp-gateway/oauth-2-1.md) 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. `2026-07-28` clients use `POST` only. See [Transport](https://tyk.io/docs/ai-management/mcp-gateway/core-concepts.md#transport). |
| **Legacy HTTP+SSE transport** (separate POST and `/sse` endpoints) | Pre-2025-03-26 | ❌ Not supported | Replaced by Streamable HTTP in the MCP specification. |
| **Stateless requests** (no session) | 2026-07-28 | ✅ Full | Tyk validates the `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` headers and the `_meta` declarations. See [MCP Protocol Versions](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md). |
| **Server discovery** (`server/discover`) | 2026-07-28 | ✅ Full | Tyk filters capabilities and supported versions against the consumer's policy, and marks filtered results as private and uncacheable. |
| **Sampling** (`sampling/createMessage`) | Pre-2025-03-26 | ⚠️ Limited | Tyk proxies the server's sampling request to the client, but rejects the client's JSON-RPC response. See [Limitations](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md#limitations). |
| **Roots** (`roots/list`) | Pre-2025-03-26 | ⚠️ Limited | Tyk proxies the server's roots request to the client, but rejects the client's JSON-RPC response. See [Limitations](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md#limitations). |
| **Elicitation** (`elicitation/create`) | 2025-06-18 | ⚠️ Limited | Tyk proxies the server's elicitation request to the client, but rejects the client's JSON-RPC response. See [Limitations](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md#limitations). |
| **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](https://tyk.io/docs/ai-management/mcp-gateway/oauth-2-1.md). |
| **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 versions:** Tyk supports the `2026-07-28` and `2025-11-25` revisions of the MCP specification. See [MCP Protocol Versions](https://tyk.io/docs/ai-management/mcp-gateway/protocol-versions.md).

## 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) |