[Proposal] MCP Server for the API Platform Gateway Controller

[Thinal-Fernando]

Overview

Currently operators of the WSO2 API Platform gateway manage APIs, credentials, policies, certificates and LLM gateway resources through raw REST calls or the console. AI agents have no supported way to perform these operations.

This post proposes an MCP server built into the Gateway Controller, exposing its Management API and read-only Admin API as MCP tools at <gateway-controller-host>/mcp over streamable HTTP.

Two central design decisions are:

• The manifest is the source of truth for what is being acted on. The resource kind is read from the submitted document rather than selected by the model or encoded in the tool name. This decouples the tool count from the number of resource kinds the gateway supports.
• The OpenAPI spec is the source of truth for who may act. Each tool's allowed scopes are declared in management-openapi.yaml and loaded at startup, rather than being configured separately or hardcoded in the tool layer.

Tool surface

An earlier iteration mapped one backend operation to one tool, producing 85 tools across 8 toolsets, plus 28 chained tools for order-sensitive workflows. The current design reduces the resource-management surface to 8 tools will still covering all 43 controller operations:

Design	Resource tools	Cost of a new resource kind
One tool per operation	85	+5 - 15 tools
One tool per operation + chains	113	+5 - 15 tools, plus chains
Consolidated (this design)	8	0 tools - one registry entry

Why now

Agent-driven administration removes a large amount of manual console and REST toil. It also aligns the API Platform with the direction adjacent WSO2 products are already taking; OpenChoreo exposes its surface over MCP - and with competitors adding agent interfaces.

Core Design Principles

1. One tool per intent, not per operation. Tools are named for what the operator wants to do (deploy_api, list_resourses), not for which backend endpoint serves it. The resource kind is a parameter, not part of the tool identity.
2. The manifest carries the kind. Every manifest kind declares kind on its request schema, so a single tool can accept any manifest, read the kind, and dispatch. The model never guesses a kind it was not given.
3. Kind dispatch through a registry. Each kind is registered once with the service calls that implement its verbs. Supporting a new kind means adding one registry entry - no new tools, no changes to the tool layer.
4. Tools call services, not HTTP. Every tool invokes the same service the corresponding REST handler invokes, in-process. Manifest parsing, validation and deployment behave identically whether a resource arrives over HTTP or over MCP.
5. Authorization is declared in the spec, enforced in two places, and fails closed. A tool with no scope mapping is denied to everyone, and the server refuses to boot if a registered tool has no mapping at all.
6. Destructive operations require explicit confirmation. Tools that delete or revoke take a confirm argument; a missing or non-true value refuses the call.

---

Architecture

---

Authorization

The spec is the source of truth

Tool → allowed-scopes is loaded from the embedded OpenAPI spec at startup. Nothing is configured per-tool in config.toml.

Operation-backed tools carry x-mcp-tool next to their existing x-basicauth-roles:

  /rest-apis:
    post:
      operationId: createRestAPI
      x-basicauth-roles: [admin, developer]
      x-mcp-tool:
        name: deploy_api
        kind: RestApi
        verb: create

The structured form matters for consolidated tools: one MCP tool maps to many operations, so kind and verb are what let the loader work out which operation's roles apply to a given call.

Helper tools with no REST operation are declared in a root block:

x-mcp-tools:
  list_schemas:            [consumer, developer, admin]
  get_schema:              [consumer, developer, admin]
  list_policies:           [consumer, developer, admin]
  get_policy:              [consumer, developer, admin]
  get_policy_requirements: [consumer, developer, admin]
  get_policy_markdown:     [consumer, developer, admin]

A tool with no entry is denied to everyone, the map is an allowlist. At startup the server checks every registered tool has a mapping and refuses to boot if one does not: an unreachable tool is a configuration bug worth failing fast on.

x-basicauth-roles is an explicit allow-list, so a token qualifies if it holds any one of the listed scopes. A non-contiguous set such as [admin, consumer] must not admit developer, which a tier ordering would wrongly do.

Why enforcement happens twice

AuthorizationMiddleware at the MCP protocol layer is authoritative - nothing executes without scope. But an MCP-layer denial becomes a JSON-RPC error inside HTTP 200, and clients read that as "the tool failed" and never re-authorize.

To make a client re-run the OAuth flow asking for the missing scope, the server has to answer the HTTP request itself:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
  error_description="The access token lacks a scope required for this tool.",
  scope="admin developer",
  resource_metadata="https://<host>/.well-known/oauth-protected-resource"

Only an http.Handler can do that, hence ScopeGate. The three challenge parameters each do a job: error=insufficient_scope tells the client to re-authorize rather than refresh; scope= names what to ask for, so the retry isn't identical to the first attempt; resource_metadata= lets a client that lost its discovery state rebuild it.

If the gate is ever bypassed, AuthorizationMiddleware still denies - the gate is an affordance, not the control.

tools/list is deliberately unfiltered

Every tool is advertised regardless of the caller's scopes. Filtering would make the step-up flow unreachable: to receive the 403 and re-authorize, the client must be able to see and attempt a tool it currently lacks scope for. Authorization happens on the call, not by omission from the list. (Flagged for review - see Open Decisions.)

Example deploy_api with a RestApi manifest

1. tools/call arrives with a manifest declaring kind: RestApi.
2. ScopeGate peeks the payload, resolves deploy_api → [admin, developer], and checks the token's scopes.
3. On success the SDK dispatches; AuthorizationMiddleware repeats the check against the per-call token.
4. Envelope parsed; kind resolved to RestApi; class checked (routable ✓).
5. Registry dispatches to RestAPIService.Create.

On failure at step 2 the client receives the 403 challenge above and can re-authorize for admin or developer without restarting the session.

---

The Manifest as the Source of Truth

Five of the six manifest kinds carry a k8s-style envelope, and all of them declare kind on the request schema:

apiVersion: gateway.api-platform.wso2.com/v1
kind: LlmProxy          # <- the kind, already in the payload
metadata:
  name: openai-proxy
spec:
  context: /openai-proxy

Write tools that accept a manifest (deploy_api, apply_config) parse this envelope and route on kind. Tools that operate on an existing resource by identity take kind as an explicit argument, normalised before use — rest_api, REST-API and RestApi all resolve to one canonical value, since models are inconsistent about casing and separators.

The spec defines six kinds: RestApi, Mcp, LlmProviderTemplate, LlmProvider, LlmProxy, Secret. Secret, Certificate, SubscriptionPlan and Subscription are out of scope.

---

Tool Reference

API lifecycle - routable kinds

Tool	Arguments	Backend operations	Kinds
deploy_api	yaml, id?	createRestAPI, updateRestAPI, createMCPProxy, updateMCPProxy, createLLMProxy, updateLLMProxy, createLLMProvider, updateLLMProvider	RestApi, Mcp, LlmProxy, LlmProvider
undeploy_api	kind, id, confirm	deleteRestAPI, deleteMCPProxy, deleteLLMProxy, deleteLLMProvider	RestApi, Mcp, LlmProxy, LlmProvider

deploy_api omits id to create and passes it to update. When id is present it must agree with metadata.name, so a mistyped id cannot overwrite the wrong resource.

Config lifecycle - non-routable kinds

Tool	Arguments	Backend operations	Kinds
apply_config	yaml, id?	createLLMProviderTemplate, updateLLMProviderTemplate	LlmProviderTemplate
delete_config	kind, id, confirm	deleteLLMProviderTemplate	LlmProviderTemplate

Supporting configuration is referenced by routable resources but takes no traffic itself. Certificate upload/reload is intended for this pair once certificates come into scope.

Read - all kinds

Tool	Arguments	Backend operations	Kinds
list_resources	kind?	listRestAPIs, listMCPProxies, listLLMProxies, listLLMProviders, listLLMProviderTemplates	all
get_resource	kind, id	getRestAPIById, getMCPProxyById, getLLMProxyById, getLLMProviderById, getLLMProviderTemplateById	all

list_resources with a kind returns full manifests. Without a kind it returns a cross-kind inventory, per-kind counts plus a compact summary. So a bare call stays small enough to be a useful starting point.

Credentials (need to be discussed)

Tool	Arguments	Backend operations	Kinds
issue_api_key	kind, id, keyName	createAPIKey, createLLMProviderAPIKey, createLLMProxyAPIKey	RestApi, LlmProvider, LlmProxy
list_api_keys	kind, id	listAPIKeys, listLLMProviderAPIKeys, listLLMProxyAPIKeys	RestApi, LlmProvider, LlmProxy
rotate_api_key	kind, id, keyName, metadata?	regenerateAPIKey, updateAPIKey, and LLM equivalents	RestApi, LlmProvider, LlmProxy
revoke_api_key	kind, id, keyName, confirm	revokeAPIKey, revokeLLMProviderAPIKey, revokeLLMProxyAPIKey	RestApi, LlmProvider, LlmProxy

rotate_api_key merges regeneration with an optional metadata update, since the two are almost always performed together.

Diagnostics - admin port (needs to be discussed)

Tool	Arguments	Backend operations
get_gateway_status	—	getHealth, getXDSSyncStatus
get_config_dump	section?	getConfigDump

get_gateway_status returns liveness plus the current policy-chain xDS version, which is what makes it useful before and after a deploy to confirm a change actually applied. section accepts apis, policies, certificates, statistics, or all (default: summary).

---

Kind Registry

Each kind is registered once with the service calls implementing its verbs. Routable determines which tool pair owns its write path.

Kind	Routable	Write tools	Backing service
RestApi	yes	deploy_api / undeploy_api	RestAPIService
Mcp	yes	deploy_api / undeploy_api	MCPDeploymentService
LlmProxy	yes	deploy_api / undeploy_api	LLMDeploymentService
LlmProvider	yes	deploy_api / undeploy_api	LLMDeploymentService
LlmProviderTemplate	no	apply_config / delete_config	LLMDeploymentService

Adding a New Kind

Adding a resource kind requires one registry entry, one alias, and x-mcp-tool annotations on its operations. No tool is added, renamed or modified:

func (h *McpHandler) webSubAPIOps() *kindOps {
    return &kindOps{
        Kind:     models.KindWebSubApi,
        Routable: true,
        Create:   func(manifest []byte, correlationID string, log *slog.Logger) (any, error) { ... },
        Update:   func(handle string, manifest []byte, ...) (any, error) { ... },
        Delete:   func(handle, correlationID string, log *slog.Logger) error { ... },
        Get:      func(handle string) (any, error) { ... },
        List:     func() ([]listedResource, error) { ... },
    }
}

---

Tool Selection Rules

Rule 1 - One tool per intent, not per operation

Tool identity is the verb, never the noun. create_rest_api, create_mcp_proxy and create_llm_proxy are one tool (deploy_api) because they are one intent. Splitting them forces the model to choose between near-identical descriptions, which is where selection errors come from.

Rule 2 - The kind is never invented

Source of kind	Tools
Read from the manifest envelope	deploy_api, apply_config
Explicit argument, normalised	undeploy_api, delete_config, list_resources, get_resource, credential tools

Rule 3 - Destructive tools require explicit confirmation

Tool	Guard
undeploy_api	confirm: true
delete_config	confirm: true
revoke_api_key	confirm: true

A missing key, a non-boolean value, or false all refuse the call, so the guard is closed by default.

Rule 4 - Write tools are class-scoped; read tools are not

deploy_api / undeploy_api accept only routable kinds. apply_config / delete_config accept only supporting configuration. list_resources / get_resource accept every kind.

A rejection names the tool that does own the kind - "kind LlmProviderTemplate is a supporting configuration, not a routable resource; use apply_config or delete_config for it" - so a caller that picks wrong corrects itself without another round trip to the user.

Rule 5 - Validation errors are surfaced, infrastructure errors are not

Manifest shape is not validated at the tool layer. The same service layer the REST endpoints use parses and validates every manifest, and its validation errors are returned to the caller verbatim, because that is how an assistant learns to correct a document and retry. Storage and infrastructure failures are logged with a correlation id and returned as a sterile message.

---

MCP Server - Auth related configs

Mode 1: No-auth (development only)

With no IdP configured the gateway already runs unauthenticated by design; enforceScopes is false and every tool is open. This is an explicit, logged branch rather than an accidental fall-through.

Mode 2: External IdP with OIDC discovery

[controller.auth.idp]
enabled      = true
jwks_url     = "https://api.asgardeo.io/t/<org>/oauth2/jwks"
issuer       = "https://api.asgardeo.io/t/<org>/oauth2/token"
roles_claim  = "groups"
scopes_claim = "scope"
# MUST match the IdP API Resource identifier AND the "resource" field of the
# RFC 9728 document. Without it, any token issued by this org is accepted here.
audience     = ["<api-resource-identifier>"]

[controller.mcp]
enabled = true
# Baseline scopes advertised to clients (RFC 9728 scopes_supported). The per-tool
# mapping is NOT here — it is derived from the OpenAPI spec.
advertised_scopes = ["consumer"]

[controller.server]
# Public origin MCP clients reach this controller on. Required for RFC 9728
# discovery — without it clients assume this server is its own authorization
# server and fail on /authorize.
external_base_url = "http://localhost:9090"

GET /.well-known/oauth-protected-resource returns:

{
  "resource": "<external_base_url>/mcp",
  "authorization_servers": ["https://api.asgardeo.io/t/<org>/oauth2/token"],
  "scopes_supported": ["admin", "consumer", "developer"],
  "bearer_methods_supported": ["header"]
}

scopes_supported is computed from the union of every tool's allowed scopes, so it cannot drift from what the server actually enforces.

Basic auth remains available and is what the REST API already uses (controller.auth.basic, bcrypt-hashed passwords, local roles). It is appropriate for local development only: credentials travel on every request, there is no expiry or scoped access, revocation needs a config change plus restart, and it is not referenced by RFC 9728.

Static bearer tokens were considered and rejected - no built-in expiry, manual rotation and out-of-band distribution, and no identity or role claims unless embedded in a signed JWT, at which point it is a simplified OIDC reimplementation.

---

Open Decisions

1. Scope naming. Allowed scopes are currently the role names already in x-basicauth-roles - admin, developer, consumer. Adopting it means x-basicauth-roles is no longer the right source and a parallel x-required-scopes is needed.
2. Admin and Management port separation. Two backends behind one MCP server (management 9090, admin 9094/9092). Single server with per-tool routing, or separate endpoints?