# Register an MCP Proxy

An **MCP Proxy** is an organization-level resource that fronts one or more upstream [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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[​](#how-the-proxy-is-deployed "Direct link to 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[​](#prerequisites "Direct link to 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](/agent-manager/docs/v1.0.0-alpha1/administration/register-ai-gateway/.md))
* 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[​](#step-1-navigate-to-mcp-proxies "Direct link to Step 1: Navigate to MCP Proxies")

1. Log in to the WSO2 Agent Manager Console (`http://console.amp.localhost:8080`).

2. Go to the Organization level by closing the projects section from the top navigation.

3. 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[​](#step-2-create-a-proxy "Direct link to Step 2: Create a Proxy")

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

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

3. 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](#step-3-add-an-endpoint)). Repeat for each backend you want to serve different environments.

4. 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[​](#step-3-add-an-endpoint "Direct link to Step 3: Add an Endpoint")

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

1. Enter the **MCP Proxy Endpoint URL** *(required)* — the upstream MCP server this endpoint connects to (e.g., `https://api.example.com/mcp`).

2. *(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.

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

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

5. Click **Add**. The endpoint appears in the **Endpoints** list, tagged with the environments it serves and whether it uses authentication.

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

***

## Step 4: Configure Proxy Settings[​](#step-4-configure-proxy-settings "Direct link to 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[​](#overview-tab "Direct link to 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[​](#capabilities-tab "Direct link to 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[​](#connection-tab "Direct link to 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[​](#access-control-tab "Direct link to 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[​](#security-tab "Direct link to 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[​](#rewrite-tab "Direct link to 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[​](#policies-tab "Direct link to 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[​](#verifying-the-proxy "Direct link to 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](/agent-manager/docs/v1.0.0-alpha1/tutorials/configure-agent-mcp-proxies/.md).

***

## Notes[​](#notes "Direct link to 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](/agent-manager/docs/v1.0.0-alpha1/tutorials/configure-agent-mcp-proxies/.md).
* 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[​](#next-steps "Direct link to 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](/agent-manager/docs/v1.0.0-alpha1/tutorials/configure-agent-mcp-proxies/.md).