[Proposal] Subscription support for MCP proxies

[AqeelMuhammad]

Summary

Extend the API subscription model introduced in #1315 (plans, the subscription-validation policy, subscription tokens) to MCP proxies.

• An MCP proxy can be offered under selected subscription plans.
• Consumers subscribe from the API Portal / MCP Hub (or through Platform API) and call the MCP server with a Subscription-Key.
• The AI Gateway allows, rejects (403) or rate-limits (429) every MCP call according to the subscription and its plan.

Tracking issue: #3787. Feedback welcome on the design and on the review questions at the end.

---

Problem Statement

• Subscriptions, subscription plans and subscription validation exist for REST APIs ([Proposal] API Subscription Support For API Platform #1315) but not for MCP proxies.
  • A plan can't be attached to an MCP proxy.
  • If subscription-validation is attached to an MCP proxy, every call returns 403, even with a valid subscription token, because the gateway only loads subscriptions for REST APIs.
  • There is no per-subscriber quota on MCP traffic.
• MCP servers exposed through the AI Gateway can only be protected with authentication (API key / OAuth2), which is all-or-nothing. A provider can't offer the same MCP server at different service levels (e.g. 5 requests/minute free, 10,000/hour paid), and can't revoke or suspend one consumer's access without affecting others.
• The API Portal already lists MCP servers (MCP Hub), but there is no working "subscribe to an MCP server under a plan" path, end to end.

Who are we solving the problem for?

• Org admins: define subscription plans once (already possible) and have them apply to MCP servers too.
• MCP proxy developers / API product owners: decide which plans an MCP server is offered under, and require a subscription.
• Consumers (app and agent developers): discover an MCP server in the MCP Hub, subscribe under a plan, and plug the token into their MCP client (IDE agent, Claude/ChatGPT connector, custom agent).
• Platform operators: see and manage who is using an MCP server, and at what plan.

Why should it be solved?

• MCP servers are now a primary way AI agents reach enterprise data and tools. Providers need the same commercial and operational controls they have for APIs: plans, quotas, per-consumer lifecycle.
• Customers have asked for subscription support for MCP servers on the MCP Hub.
• One subscription model for APIs and MCP servers keeps the API Portal, the Platform API and the gateway consistent. Consumers get a token the same way, operators manage subscriptions in one place.

---

Use Cases

Platform API (control plane)

1. Org admin defines plans, e.g. gold = 10,000 requests/hour and five-per-minute = 5 requests/minute (/subscription-plans; exists today).
2. MCP proxy developer enables a subset of plans for an MCP proxy (subscriptionPlans).
3. MCP proxy developer requires a subscription for the MCP proxy (attaches subscription-validation).
4. MCP proxy developer deploys the MCP proxy to a gateway.
5. MCP proxy developer / operator lists, suspends or removes the subscriptions of an MCP proxy.
6. CI/CD or an external system automates all of the above.

API Portal / MCP Hub

7. Consumer browses an MCP server, sees "Subscription required" and the available plans.
8. Consumer subscribes under a plan and gets a subscription token and a ready-to-use MCP client config.
9. Consumer calls tools through the gateway with Subscription-Key (plus API-Key / OAuth2 if the MCP proxy also requires authentication).
10. Consumer changes plan, regenerates the token or unsubscribes.

AI Gateway (runtime)

11. A call without a valid, active subscription → 403.
12. A call over the plan's quota in the current window → 429 with ratelimit-* / retry-after headers.
13. A suspended subscription → 403; resumed → allowed again. A regenerated token invalidates the old one.

---

Proposed Solution

Overview

flowchart TB
  DEV["MCP proxy developer / org admin<br/>(Platform API REST · CLI · CI)"]
  ADM["Portal admin"]
  PA[("Platform API<br/>subscription_plans · mcp_proxies (+subscriptionPlans)<br/>subscriptions · events")]
  subgraph PORTAL["API Portal / MCP Hub"]
    HUB["MCP server page<br/>plans · Subscribe · token · API key"]
  end
  subgraph GW["AI Gateway"]
    direction LR
    GC[("gateway-controller<br/>plans · MCP spec · subscriptions")]
    PE["policy engine<br/>subscription-validation"]
    EN["Envoy"]
  end
  C["MCP client / agent"]
  UP["Upstream MCP server"]

  DEV -->|"plans · MCP proxy + subscriptionPlans · deploy"| PA
  ADM -->|"① add MCP server<br/>(mcp.yaml: referenceId + plans)"| HUB
  HUB -->|"② webhook subscription.* / apikey.*"| PA
  PA ==>|"③ WebSocket events<br/>mcpproxy.deployed · subscriptionPlan.* · subscription.*"| GC
  GC -.->|"REST pull on (re)connect"| PA
  GC -->|"xDS routes"| EN
  GC -->|"xDS PolicyChain + SubscriptionState"| PE
  C -->|"④ POST /ctx/mcp<br/>Subscription-Key (+ API-Key)"| EN
  EN <-->|ext_proc| PE
  EN --> UP

Loading

User flow

flowchart TD
  A["① Org admin<br/>creates plans<br/>POST /subscription-plans (exists today)"] --> B["② MCP proxy developer<br/>sets subscriptionPlans + subscription-validation<br/>PUT /mcp-proxies/{id}"]
  B --> C["③ Deploy to gateway<br/>proxy + policy + plans"]
  C --> D["④ Add to API Portal / MCP Hub<br/>mcp.yaml with referenceId + plans"]
  D --> E["⑤ Consumer (MCP Hub)<br/>pick a plan → Subscribe → token"]
  E --> F["⑥ Configure MCP client<br/>Subscription-Key (+ API-Key)"]
  F --> G{"⑦ Call the MCP server"}
  G -->|valid, within quota| H["200 · tools work"]
  G -->|no / invalid / suspended token| I["403"]
  G -->|quota used up| J["429 + ratelimit-* headers"]
  E --> K["⑧ Manage: change plan · regenerate token · unsubscribe"]

Loading

1. Org admin defines plans (no change): POST /api/v0.9/subscription-plans.

2. MCP proxy developer enables plans and requires a subscription. Set subscriptionPlans and attach subscription-validation on the MCP proxy:

curl -X PUT https://<platform-api>/api/v0.9/mcp-proxies/openai-docs-mcp -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "id": "openai-docs-mcp", "displayName": "OpenAI Docs MCP", "version": "v1.0", "projectId": "my-project",
  "context": "/openai-docs-mcp", "upstream": { "main": { "url": "https://developers.openai.com/mcp" } },
  "subscriptionPlans": ["gold", "five-per-minute"],
  "policies": [ { "name": "subscription-validation", "version": "v1", "params": { "subscriptionKeyHeader": "Subscription-Key" } } ]
}'

3. Deploy. POST /api/v0.9/mcp-proxies/openai-docs-mcp/deployments {"name": "v1.0", "base": "current", "gatewayId": "my-gateway"}. The proxy, its policy and its enabled plans go to the gateway; existing subscriptions are pushed with the deployment.

4. Add to the API Portal / MCP Hub. Until publishing from Platform API is available (a separate feature), the portal admin adds the MCP server with mcp.yaml (spec.referenceId: openai-docs-mcp, spec.subscriptionPlans: [Gold, FivePerMinute]).

5. Consumer subscribes in the MCP Hub. The MCP server page shows "Subscription required" and the plans.

6. Consumer gets the token and a ready MCP client config (Subscription-Key, and API-Key if the proxy also requires one).

7. Consumer calls the MCP server with the headers: 200 within quota, 429 when the plan's quota is used up, 403 without a valid subscription.

8. Consumer manages subscriptions: change plan, regenerate token, unsubscribe. APIs and MCP servers are listed together.

If the MCP proxy has no authentication policy

Invoke with the subscription token only:

POST /openai-docs-mcp/mcp
Subscription-Key: <subscription token>

If the MCP proxy also has api-key-auth / OAuth2

Invoke with both credentials, as for REST in #1315:

POST /openai-docs-mcp/mcp
API-Key: <api key>
Subscription-Key: <subscription token>

---

Implementation

1. Platform API

a) subscriptionPlans on MCP proxies. Same field and rules as RESTAPI.subscriptionPlans:

# resources/openapi.yaml → components.schemas.MCPProxy
subscriptionPlans:
  type: array
  description: |
    Subscription plan ids enabled for this MCP proxy (e.g. gold, five-per-minute).
    When set, only these plans can be used when subscribing to it.
  items:
    type: string
  example: [gold, five-per-minute]

• Create/update validate each plan (exists, ACTIVE) → 400 otherwise. Reuse the REST validation by moving it to a shared helper.
• Stored in the MCP proxy's configuration JSON, as REST does. No schema change (see DB changes).
• Returned by GET /mcp-proxies/{id}.

b) Deployment artifact. The MCP deployment YAML sent to the gateway carries the plans:

apiVersion: gateway.api-platform.wso2.com/v1
kind: Mcp
metadata:
  name: openai-docs-mcp
spec:
  displayName: OpenAI Docs MCP
  version: v1.0
  context: /openai-docs-mcp
  specVersion: "2025-06-18"
  upstream:
    url: https://developers.openai.com/mcp
  subscriptionPlans:          # NEW
    - gold
    - five-per-minute
  policies:
    - name: subscription-validation
      version: v1
      params:
        subscriptionKeyHeader: Subscription-Key

c) Subscriptions for MCP proxies. The existing API with kind: Mcp:

curl -X POST https://<platform-api>/api/v0.9/subscriptions -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"artifactId":"openai-docs-mcp","kind":"Mcp","subscriberId":"dev-1","subscriptionPlanId":"gold"}'
# 201 → { "id": "...", "kind": "Mcp", "subscriptionToken": "<64 hex>", "status": "ACTIVE", ... }

• Only plans enabled on the artifact are accepted → 400 SUBSCRIPTION_PLAN_NOT_ENABLED otherwise (for every subscribable kind).
• Lifecycle: PUT /subscriptions/{id} (status, exists; plan change, NEW, with the same plan check), POST /subscriptions/{id}/regenerate-token (NEW), DELETE (exists).
• GET /subscriptions?artifactId=<mcp handle> lists an MCP proxy's subscriptions (operator view).

d) Events to gateways (existing WebSocket events; payloads unchanged):

• subscription.created|updated|deleted for MCP subscriptions, sent to gateways where the MCP proxy is deployed.
• On deploy / restore, the proxy's existing subscriptions are sent to that gateway, as API keys already are.

e) Gateway sync endpoint. The gateway's reconnect sync must be able to fetch MCP subscriptions: make GET /api/internal/v1/apis/{id}/subscriptions kind-agnostic (artifact UUID), or add /api/internal/v1/mcp-proxies/{id}/subscriptions.

f) API Portal webhooks. subscription.* / apikey.* events with data.api.type = "Mcp" resolve the MCP proxy by ref_id. The plan check from (c) applies.

2. AI Gateway

a) MCP spec: MCPProxyConfigData.subscriptionPlans in the management OpenAPI; stored with the MCP config.

b) Gateway controller:

• Include MCP proxies when building the policy-engine SubscriptionState, using a set of subscribable kinds (RestApi, Mcp; GraphQLApi as a follow-up). Map the subscription's API id to the MCP config, including the CPArtifactID mapping for gateway-originated proxies.
• Store/update/delete MCP subscriptions from events; fetch MCP subscriptions on connect/reconnect.
• Remove an MCP proxy's subscriptions when it is undeployed or deleted.
• Management API (gateway-local mode): create/list/update/delete subscriptions for MCP proxies; reject plans not enabled on the proxy.

c) Policy (subscription-validation) on MCP routes (headers-only, works with SSE responses):

Case	Response
No / unknown / inactive token	403 {"error":"forbidden","message":"Subscription required for this API"}
Over quota (window = plan unit: minute / hour / day / month)	429 + ratelimit-limit, ratelimit-remaining, ratelimit-reset, ratelimit-policy, retry-after
Valid	pass; Subscription-Key stripped before the upstream

• Plan units from Platform API (MINUTE, HOUR, DAY, MONTH) are normalised to what the policy expects (see [Bug]: Per-minute subscription plan limits are never enforced at the gateway (MINUTE is not understood by subscription-validation) #3654).
• What counts toward the quota on MCP: see the review questions. If only tools/call should count, a policy param, e.g. countMethods: ["tools/call"], reads the JSON-RPC method.

3. API Portal / MCP Hub

• MCP servers show "Subscription required" and their plans; Subscribe returns a token and an MCP client config snippet.
• Generate / revoke API keys for MCP servers from the UI (the REST endpoint exists).
• "My subscriptions" lists MCP subscriptions with change plan / regenerate / unsubscribe.

DB changes

No new tables or columns are required.

Component	Change
Platform API	mcp_proxies.configuration (JSON) gains subscriptionPlans, the same way REST APIs store it in rest_apis.configuration. subscriptions is already artifact-generic (artifact_uuid, subscription_plan_uuid, token encrypted + hash).
Gateway controller	The MCP stored config spec gains subscriptionPlans. subscriptions (api_id, subscription_token_hash, subscription_plan_id) and subscription_plans are already artifact-generic.
API Portal	None. MCP servers are api_metadata rows (type Mcp); api_subscription_plan_mappings and subscriptions already work for them.

Sequence diagrams

Configure and deploy

sequenceDiagram
  autonumber
  actor Dev as MCP proxy developer
  participant PA as Platform API
  participant GC as Gateway controller
  participant PE as Policy engine
  Dev->>PA: PUT /mcp-proxies/{id} {subscriptionPlans:[gold, five-per-minute], policies:[subscription-validation]}
  PA->>PA: validate plans (exist, ACTIVE) → store in configuration
  Dev->>PA: POST /mcp-proxies/{id}/deployments {name, base, gatewayId}
  PA-->>GC: WS mcpproxy.deployed
  GC->>PA: GET /internal/v1/mcp-proxies/{id} (spec incl. subscriptionPlans)
  GC->>GC: store spec · routes · policy chain
  PA-->>GC: WS subscription.created × N (backfill existing subscriptions)
  GC->>PE: xDS PolicyChain + SubscriptionState (MCP entries)
  GC-->>PA: deployment.ack → DEPLOYED

Loading

Subscribe from the MCP Hub

sequenceDiagram
  autonumber
  actor U as Consumer
  participant HUB as API Portal / MCP Hub
  participant PA as Platform API
  participant GC as Gateway controller
  participant PE as Policy engine
  U->>HUB: Subscribe (plan Gold)
  HUB->>HUB: check plan is offered · create subscription + token · outbox event
  HUB-->>U: 201 + subscription token
  HUB-)PA: webhook subscription.created {api.ref_id, type: Mcp, plan.ref_id, token(enc)}
  PA->>PA: verify signature · resolve MCP proxy + plan · plan ∈ subscriptionPlans? · store
  PA-)GC: WS subscription.created (only gateways with the proxy deployed)
  GC->>GC: store (token hash) · rebuild SubscriptionState incl. Mcp
  GC->>PE: xDS SubscriptionState {apiId, tokenHash, status, limit, unit}

Loading

Invoke

sequenceDiagram
  autonumber
  participant C as MCP client
  participant EN as Envoy
  participant PE as Policy engine (subscription-validation)
  participant UP as Upstream MCP server
  C->>EN: POST /openai-docs-mcp/mcp  initialize · Subscription-Key: T
  EN->>PE: ext_proc request headers
  alt no / unknown / inactive token
    PE-->>C: 403 {"error":"forbidden","message":"Subscription required for this API"}
  else count(apiId, T) > plan limit in window
    PE-->>C: 429 + ratelimit-limit / ratelimit-remaining / retry-after
  else valid
    PE->>EN: continue (strip Subscription-Key, count +1)
    EN->>UP: initialize
    UP-->>C: 200 (JSON or SSE)
  end
  Note over C,PE: tools/list and tools/call repeat the same check<br/>(what counts toward the quota: open question)

Loading

Spec changes (summary)

Spec	Change
Platform API openapi.yaml	MCPProxy.subscriptionPlans; new error SUBSCRIPTION_PLAN_NOT_ENABLED on subscription create/plan change; plan change + regenerate-token on /subscriptions/{id}
Platform API internal gateway API	MCP subscriptions available to the gateway sync (kind-agnostic /apis/{id}/subscriptions or /mcp-proxies/{id}/subscriptions)
Deployment YAML (kind: Mcp)	spec.subscriptionPlans
Gateway management API	MCPProxyConfigData.subscriptionPlans; subscriptions endpoints accept MCP proxies
subscription-validation policy definition	(only if decided) countMethods param; unit normalisation
API Portal mcp.yaml	No change (spec.referenceId, spec.subscriptionPlans already supported)
WebSocket events	No change in payloads; subscription.* sent for MCP artifacts

Backward compatibility

• subscriptionPlans is optional. MCP proxies without it behave as today.
• Older gateways ignore the new field in the MCP deployment YAML. Newer gateways with an older Platform API see an empty list.

Testing

• Unit:
  • Platform API: MCP plan validation, deployment YAML, plan-enabled check, deploy-time backfill, sync endpoint.
  • Gateway: SubscriptionState includes MCP, reconnect sync, cleanup on delete, unit normalisation.
  • Policy: 403/200/429 per unit, and the counting rule.
• Integration (tests/framework): a "secured MCP invocation" feature mirroring the REST one:
  • plans → MCP proxy with plans + policy → deploy;
  • no token 403 → subscribe → initialize/tools/list/tools/call 200;
  • over quota 429;
  • suspend 403 / resume 200;
  • regenerate (old 403, new 200);
  • delete 403;
  • an unlisted plan rejected;
  • subscribe-before-deploy works;
  • a portal-path variant;
  • all DB engines.
• E2E: a real MCP client (MCP Inspector / an IDE agent) configured with Subscription-Key; REST subscription regression.

Documentation

• How-tos:
  • offer an MCP proxy under plans (Platform API);
  • subscribe and configure an MCP client.
• Reference: the new fields, errors and headers, and what counts against the quota.

---

Review questions

1. Control-plane UI for MCP plans. This proposal covers the Platform API and the API Portal. Do we need to expose MCP plans, "require subscription" and the subscriptions list in AI Workspace?
   • AI Workspace: MCP proxies are authored there, but it shows no plans today. Options:
     • A: nothing;
     • B: a read-only "Subscription required · plans …" badge;
     • C: a full plan picker + "Require subscription" toggle.
2. AI Workspace policy editor. If a developer attaches subscription-validation from the AI Workspace policy editor, should it warn when the proxy has no plans, or require them?
3. What counts toward an MCP quota? Every JSON-RPC request (initialize, notifications/initialized, tools/list, tools/call; ~3 units before the first tool call), only tools/call, or configurable per proxy?
4. Require subscription: keep it as the explicit subscription-validation policy, or attach it automatically when plans are set?
5. Subscription without a plan on a proxy that has plans: reject (400), or assign a default plan? (Today a plan-less subscription is unlimited at the gateway.)
6. Gateway subscription sync for MCP proxies: reuse the existing internal endpoint, or add a new one? After it connects, the gateway fetches each deployed artifact's full subscription list. Today it does this only for REST APIs, through GET /api/internal/v1/apis/{apiId}/subscriptions. Options:
   • A: reuse the existing endpoint for every subscribable kind.
     • Only the artifact lookup is REST-specific (apiRepo.GetAPIByUUID). The deployment check (deployment_status by artifact UUID), the subscription listing, and the response (GatewaySubscriptionInfo with apiId) are already generic.
     • The gateway keeps one fetch function and only widens its kind filter (RestApi, Mcp, later GraphQLApi).
     • Downside: the /apis/ path now means "any artifact".
   • B: add GET /api/internal/v1/mcp-proxies/{proxyId}/subscriptions, with the same response format.
     • It matches the per-kind paths (/mcp-proxies/{proxyId}) and doesn't touch the REST path.
     • It needs a new handler, service methods, a gateway fetch function, a switch by kind, plus another endpoint for each future kind.