Copy page

Version: Next

Register an MCP Proxy

An MCP Proxy is an organization-level resource that fronts one or more upstream Model Context Protocol (MCP) servers. For each environment you configure, the proxy connects to a backend MCP server, discovers the tools, resources, and prompts it exposes, and publishes a governed endpoint through that environment's AI Gateway. Once registered, an MCP proxy can be secured, access-controlled, and rewritten independently per environment, and attached to agents across any project in the organization.

Proxying an MCP server through the platform lets you:

Authenticate clients (agents) with platform-issued API keys instead of upstream credentials.
Restrict which tools, resources, and prompts are visible to agents (access control).
Rename or remap capabilities for end users (rewrite) without changing the upstream server.
Point each environment at a different backend and apply gateway policies per environment.
Apply additional gateway policies and expose governed, per-environment endpoints.

How the proxy is deployed

An MCP proxy is multi-environment. You attach one or more endpoints to it, and each endpoint serves one or more environments. The proxy deploys one gateway artifact per configured environment to that environment's active AI Gateway — you do not pick a gateway manually.

Environments with an endpoint get a deployed artifact on their gateway.
Environments without an endpoint are simply left unconfigured (no artifact, and agents referencing the proxy there receive empty connection values).
If an environment has no active AI Gateway yet, that environment is skipped and deployed on the next proxy update once a gateway becomes available.

Agents do not embed the proxy — they reference it. Each agent resolves the proxy's per-environment endpoint at its own deploy time, so changing a proxy does not automatically redeploy the agents that use it; they pick up the change on their next deployment.

Prerequisites

Admin access to the WSO2 Agent Manager Console
At least one AI Gateway registered and active for the environments you want to configure (see Register an AI Gateway)
A reachable upstream MCP server endpoint for each environment (e.g., https://api.example.com/mcp)
Any credential the upstream MCP server requires (e.g., an API key passed in an HTTP header)

Step 1: Navigate to MCP Proxies

Log in to the WSO2 Agent Manager Console (http://console.amp.localhost:8080).
Go to the Organization level by closing the projects section from the top navigation.
In the left sidebar, click MCP Proxies under the Resources section.

The MCP Proxies page lists all registered proxies with their Name, Description, Version, and Last Updated time. Use the search bar to filter by name, version, context, or status.

Step 2: Create a Proxy

Click the Add MCP Proxy button. The create form opens.

Under Proxy Details, fill in the proxy's identity:

Field	Description	Example
Name (required)	A descriptive name for the proxy	`Production Weather MCP`
Version (required)	Version identifier	`v1.0`
Description	Optional description of the proxy's purpose	`Weather tools for production agents`
Context	The API path segment used to build the proxy's gateway endpoints	`/default/weather`

Under Endpoints, add at least one backend endpoint and assign it to environments. The section shows the helper text "Add a backend endpoint and assign it to one or more environments. Environments without an endpoint are simply left unconfigured." and a running counter such as "1 of 2 environments have an endpoint."

Click Add Endpoint and complete the dialog (see Step 3). Repeat for each backend you want to serve different environments.
Click Create. The proxy is created, its per-environment artifacts are deployed to the matching gateways, and you are returned to the MCP Proxies list.

Step 3: Add an Endpoint

The Add Endpoint dialog maps a backend MCP server to one or more environments.

Enter the MCP Proxy Endpoint URL (required) — the upstream MCP server this endpoint connects to (e.g., https://api.example.com/mcp).
(Optional) If the upstream server requires authentication, expand Advanced Configurations and fill in the header sent to the endpoint:

Field Description Example
Header The HTTP header name used to pass the upstream credential Authorization
Value The credential value (hidden by default; toggle visibility with the eye icon) Bearer sk-...

Header and Value must be provided together — supply both or neither. A stored credential is shown masked; leave it unchanged to keep the current value.
Under Environments (required), select the environments this endpoint serves. Each environment can be assigned to only one endpoint, so environments already claimed by another endpoint are not offered.
Click Fetch Server Info. The proxy connects to the endpoint and discovers its capabilities.
- On success, a preview shows the Tools, Resources, and Prompts exposed by the server, each with a count. You can click Re-fetch Server Info later to pick up newly added capabilities.
- If the server returns 401 Unauthorized, expand Advanced Configurations, add the header and value, and fetch again.
Click Add. The endpoint appears in the Endpoints list, tagged with the environments it serves and whether it uses authentication.

Field	Description	Example
Header	The HTTP header name used to pass the upstream credential	`Authorization`
Value	The credential value (hidden by default; toggle visibility with the eye icon)	`Bearer sk-...`

You must fetch server info and select at least one environment before the endpoint can be added.

Step 4: Configure Proxy Settings

Click a proxy in the list to open its detail page. The header shows the proxy name, version, context, and description (click the edit icon to rename or re-version).

Because a proxy is configured per environment, the detail page has two controls above the tabs:

Environment selector — choose which configured environment's settings the tabs display and edit. Only environments that have an endpoint appear here; if none are configured, the page shows "This MCP proxy has no environments configured."
Manage Endpoints — opens the Manage Endpoints dialog to add, edit, or remove endpoints after creation. Editing an endpoint updates the upstream URL, authentication, and capabilities for every environment it serves; environments left without an endpoint become unconfigured.

Configuration is organized into the tabs below. When you change a setting, an unsaved changes banner appears — click Save to persist or Cancel/Discard to revert. All tabs except Overview and Capabilities apply to the environment currently selected above.

Overview Tab

Displays a read-only summary of the proxy for the selected environment:

Field	Description
Context	The context path used to build the proxy's endpoints
Upstream URL	The backend MCP server endpoint for this environment
Auth Type	The inbound authentication clients must present — `API Key` or `None` (configured on the Security tab)
Access Control	`Allow all` (default) or `Configured`
Deployment	`Deployed` or `Undeployed` — whether this environment's gateway artifact is currently deployed
In Catalog	Whether the proxy is published to the catalog

Capabilities Tab

Lists everything the selected environment's endpoint exposes, grouped into three sections — Tools, Resources, and Prompts — each with a total count. Expand a section to browse individual items and their descriptions. Capabilities are captured when you fetch server info for the endpoint.

Connection Tab

Manage the upstream connection for the selected environment:

Field	Description	Example
MCP Proxy Endpoint URL (required)	The upstream MCP server endpoint	`https://api.example.com/mcp`
Header	(under Advanced Configurations) HTTP header sent to the upstream server	`Authorization`
Value	The credential value for that header	`Bearer sk-...`

A stored credential is shown masked (••••••••••••). "The stored value is hidden. Leave it unchanged to keep the current credential, or enter a new value to replace it."

Click Save to persist changes, or Discard to revert.

Access Control Tab

Control which capabilities are reachable through the proxy in the selected environment:

Mode: Choose Allow all (default – every tool, resource, and prompt is permitted) or Deny all (block everything except listed exceptions).
Exceptions: Tools, resources, and prompts to exclude from the selected mode. In Allow all mode these are denied; in Deny all mode these are the only items allowed. Items are grouped and color-coded by kind (Tools, Resources, Prompts).

Click Save to apply. This is backed by the managed mcp-acl-list policy.

If the environment's endpoint has no capabilities, access control is unavailable. If the environment's active gateway does not report the mcp-acl-list policy as available, saving is disabled.

Security Tab

Configure how clients (agents) authenticate to the proxy through the gateway, for the selected environment:

Field	Description	Example
Authentication Method	`apiKey` (default) or `None`	`apiKey`
Key Location	(when `apiKey` is selected) Where the key is passed — `header` or `query`	`header`
Header Key / Query Param Key	(when `apiKey` is selected) The header or query parameter carrying the API key	`X-API-Key`

Click Save to persist.

Rewrite Tab

Customize the user-facing names of the capabilities exposed by the proxy in the selected environment, without modifying the upstream server. Toggle Rewrite on to enable editing.

When enabled, the left panel lists the capabilities (Tools, Resources, Prompts). Select an item to edit its presented values in the right panel:

Tools: Name, Description, Input Schema, and (under Advanced) Output Schema and Target (the backend tool name calls are forwarded to).
Resources: URI, Description, and (under Advanced) Target (the backend resource URI reads are forwarded to).
Prompts: Name, Description, and (under Advanced) Target (the backend prompt name requests are forwarded to).

The backend identifier is what is sent to the upstream MCP server. Rewriting the values controls only what clients see.

Click Save to apply. This is backed by the managed mcp-rewrite policy.

If the environment's active gateway does not report the mcp-rewrite policy as available, saving is disabled.

Policies Tab

Attach additional gateway policies for the selected environment, beyond the managed ones (access control, security, and rewrite are managed through their dedicated tabs and do not appear here).

Click Add Policy to choose and configure a policy.
Use the edit and remove controls on each policy, and drag policies to change their execution order.

Verifying the Proxy

The registered proxy appears in the MCP Proxies list with its name, description, and version. Open the detail page and, for each configured environment, confirm on the Overview tab that Deployment shows Deployed and check the Capabilities tab for the expected tools, resources, and prompts. The endpoint agents actually use is exposed to them when they attach the proxy — see Configure MCP Proxies for an Agent.

Notes

A proxy deploys one gateway artifact per configured environment to that environment's active AI Gateway. Environments without an endpoint, or without an active gateway, are left unconfigured until you add one.
The context forms part of each environment's endpoint. Keep it unique per organization.
Upstream credentials entered on the Connection tab (or the endpoint dialog) are stored securely and shown masked; they are never returned in plain text.
Access control (mcp-acl-list) and rewrite (mcp-rewrite) require the corresponding policy to be available on the selected environment's active gateway; otherwise saving on those tabs is disabled.
Client API keys are not generated on the proxy itself. They are minted and managed per agent configuration and environment when a proxy is attached to an agent — see Configure MCP Proxies for an Agent.
Changing a proxy does not redeploy the agents that reference it. Each agent resolves the proxy's endpoint at its own next deployment.
The proxy is published using MCP specification version 2025-06-18.

Next Steps

Once a proxy is registered, attach it to an agent so the agent can use its tools, resources, and prompts — see Configure MCP Proxies for an Agent.

How the proxy is deployed​

Prerequisites​

Step 1: Navigate to MCP Proxies​

Step 2: Create a Proxy​

Step 3: Add an Endpoint​

Step 4: Configure Proxy Settings​

Overview Tab​

Capabilities Tab​

Connection Tab​

Access Control Tab​

Security Tab​

Rewrite Tab​

Policies Tab​

Verifying the Proxy​

Notes​

Next Steps​