Copy page

Version: Next

Register an MCP Proxy

An MCP Proxy is an organization-level resource that fronts an upstream Model Context Protocol (MCP) server. It connects to the upstream server's endpoint, discovers the tools, resources, and prompts it exposes, and republishes them through an AI Gateway. Once registered, an MCP proxy can be secured, access-controlled, rewritten, 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.
Apply additional gateway policies and expose a single, governed invoke URL.

Prerequisites

Admin access to the WSO2 Agent Manager Console
At least one AI Gateway registered and active (see Register an AI Gateway)
A reachable upstream MCP server endpoint (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://localhost:3000).
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 from an Endpoint

Click the Add MCP Proxy button. The Create MCP Proxy from Endpoint page opens.
Under Endpoint Details, enter the MCP Proxy Endpoint URL (required) — the URL of the upstream MCP server you want to proxy.

Field Description Example
MCP Proxy Endpoint URL (required) The upstream MCP server endpoint the proxy connects to https://api.example.com/mcp
(Optional) If the upstream server requires authentication, expand Advanced Configurations and fill in the authentication 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.
Click Fetch Server Info. The proxy connects to the endpoint and discovers its capabilities.
- On success, a preview panel appears on the right showing the Tools, Resources, and Prompts exposed by the server, each with a total count. Click Next to continue.
- If the server returns 401 Unauthorized, the Advanced Configurations section opens automatically with the message "This server requires authentication. Enter the credentials above." Add the header and value, then fetch again.

Field	Description	Example
MCP Proxy Endpoint URL (required)	The upstream MCP server endpoint the proxy connects to	`https://api.example.com/mcp`

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-...`

Step 3: Provide Proxy Details

After a successful fetch, the form advances to Proxy Details. Several fields are pre-populated from the server info — review and adjust them.

Field	Description	Example
Name (required)	A descriptive name for the proxy (defaults to the upstream server name)	`Production Weather MCP`
Version (required)	Version identifier (auto-derived from the URL or server info)	`v1.0`
Description	Optional description of the proxy's purpose	`Weather tools for production agents`
Context	The API path segment used to build the invoke URL (auto-set to `/default/{name}`)	`/default/weather`
Target (required)	The upstream MCP server URL (pre-filled from Step 2, read-only)	`https://api.example.com/mcp`
Gateway (required)	One or more active AI Gateways that will expose this proxy	`Production Gateway`

If no active gateways exist, the message "No active gateways available." appears. Register and activate an AI Gateway first.

Click Create. The proxy is created and you are returned to the MCP Proxies list.

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). Configuration is organized into the tabs below. When you change a setting, an unsaved changes banner appears — click Save to persist or Cancel to revert.

Overview Tab

Displays a summary of the proxy and lets you generate client API keys:

Field	Description
Context	The context path used in the invoke URL
Upstream URL	The backend MCP server endpoint
Auth Type	Authentication used toward the upstream server (e.g., `api-key`)
Access Control	`Allow all` (default) or `Configured`
In Catalog	Whether the proxy is published to the catalog

The Invoke URL section lets you:

Gateway: Select which AI Gateway exposes this proxy.
Invoke URL: The full URL agents use to reach the proxy through the gateway (auto-generated as <gateway-vhost><context>/mcp). Use the copy button to copy it.
Generate API Key: Generate (or rotate) a client API key for agents to authenticate against this proxy on the selected gateway. The key is shown only once — copy it immediately.

If the proxy has not been deployed to any gateway, the message "No invoke URLs available. Deploy this MCP proxy to an AI gateway to see invoke URLs and generate API keys." appears.

Capabilities Tab

Lists everything the proxy exposes, grouped into three expandable sections — Tools, Resources, and Prompts — each with a total count. Expand a section to browse individual items and their descriptions.

Connection Tab

Manage the upstream connection:

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 (••••••••••••). 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:

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 proxy has no capabilities, access control is unavailable. If the 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:

Field	Description	Example
Authentication	`apiKey` (default, enabled on create) or `None`	`apiKey`
Header Key	(when `apiKey` is selected) The HTTP header carrying the API key	`X-API-Key`
Key Location	(when `apiKey` is selected) Where the key is passed — `header` or `query`	`header`

Click Save to persist.

Rewrite Tab

Customize the user-facing names of the capabilities exposed by the proxy 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 active gateway does not report the mcp-rewrite policy as available, saving is disabled.

Policies Tab

Attach additional gateway policies 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. From the Overview tab, select your active AI Gateway to see the Invoke URL — this is the endpoint agents use to reach the proxied MCP server through the gateway. Generate an API key and confirm the proxy responds with the expected tools, resources, and prompts on the Capabilities tab.

Notes

A proxy must be deployed to at least one active AI Gateway before its invoke URL and API keys become available.
The context forms part of the invoke URL: <gateway-vhost><context>/mcp. Keep it unique per organization.
Upstream credentials entered on the Connection tab 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 active gateway; otherwise saving on those tabs is disabled.
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.

Prerequisites​

Step 1: Navigate to MCP Proxies​

Step 2: Create a Proxy from an Endpoint​

Step 3: Provide Proxy Details​

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​