# Register an MCP Proxy

An **MCP Proxy** is an organization-level resource that fronts an upstream [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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[​](#prerequisites "Direct link to Prerequisites")

* Admin access to the WSO2 Agent Manager Console
* At least one AI Gateway registered and active (see [Register an AI Gateway](/agent-manager/docs/next/administration/register-ai-gateway/.md))
* 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[​](#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://localhost:3000`).

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

1. Click the **Add MCP Proxy** button. The **Create MCP Proxy from Endpoint** page opens.

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

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

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

***

## Step 3: Provide Proxy Details[​](#step-3-provide-proxy-details "Direct link to 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[​](#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). 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[​](#overview-tab "Direct link to 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[​](#capabilities-tab "Direct link to 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[​](#connection-tab "Direct link to 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[​](#access-control-tab "Direct link to 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[​](#security-tab "Direct link to 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[​](#rewrite-tab "Direct link to 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[​](#policies-tab "Direct link to 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[​](#verifying-the-proxy "Direct link to 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[​](#notes "Direct link to 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[​](#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/next/tutorials/configure-agent-mcp-proxies/.md).