# Configure MCP Proxies for an Agent

Agents can be configured to use one or more [MCP Proxies](/agent-manager/docs/next/tutorials/register-mcp-proxy/.md) registered at the organization level. Each binding — called an **MCP configuration** — maps an org-level MCP proxy to the agent and exposes the proxy's invoke URL and API key to the agent's code. The configuration process differs slightly between **Platform-hosted** and **External** agents, but both follow the same pattern: attach an org-level proxy to the agent.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* At least one MCP Proxy registered at the org level (see [Register an MCP Proxy](/agent-manager/docs/next/tutorials/register-mcp-proxy/.md))
* An agent created in a project (Platform-hosted or External)

***

## Overview: Agent Types[​](#overview-agent-types "Direct link to Overview: Agent Types")

| Type         | Description                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Platform** | Agent code is built and deployed by the platform from a GitHub repository. The platform injects the MCP server URL and API key as environment variables. |
| **External** | Agent is deployed and managed externally. The platform provides the gateway endpoint URL + API key for the MCP proxy so the agent can connect to it.     |

***

## Configuring an MCP Proxy for a Platform-Hosted Agent[​](#configuring-an-mcp-proxy-for-a-platform-hosted-agent "Direct link to Configuring an MCP Proxy for a Platform-Hosted Agent")

### Step 1: Open the Agent[​](#step-1-open-the-agent "Direct link to Step 1: Open the Agent")

1. Navigate to your project (**Projects** → select project → **Agents**).
2. Click on a **Platform**-tagged agent.
3. In the left sidebar, click **Configure**.

### Step 2: Add an MCP Configuration[​](#step-2-add-an-mcp-configuration "Direct link to Step 2: Add an MCP Configuration")

The **Configure** page displays the **MCP Configurations** section listing all MCP configurations currently attached to this agent.

1. Click **Add MCP Configuration**.

2. Under **MCP Server**, click **Select an MCP Server**.

   <!-- -->

   * A side panel titled **Select MCP Server** opens, listing all org-level MCP proxies with their name, description, context, and version. Use the **Search MCP servers** box to filter.
   * Select the desired proxy. The panel closes automatically.
   * If none are listed, the panel prompts you to *"Add MCP servers from the organization MCP Proxies page first."*

3. Click **Save**.

> **Multiple environments**: If your organization has more than one environment, tabs appear above the server selector — one per environment, with the helper text *"Select which MCP server to use in each environment."* Select a server for each environment tab before saving. Tabs with no server selected are marked with a warning indicator.

### Step 3: Set Environment Variable Names[​](#step-3-set-environment-variable-names "Direct link to Step 3: Set Environment Variable Names")

Selecting a server reveals the **Environment Variable Names** section, showing the two environment variables the platform will inject into the agent at runtime:

| Variable Key | Default Name (example) | Description                                             |
| ------------ | ---------------------- | ------------------------------------------------------- |
| `url`        | `MY_PROXY_URL`         | Base URL of the MCP server endpoint                     |
| `apikey`     | `MY_PROXY_API_KEY`     | API key for authenticating with the MCP server endpoint |

The names are auto-generated from the selected proxy's ID (uppercased, non-alphanumeric characters replaced with `_`; e.g., a proxy `my-proxy` yields `MY_PROXY_URL` and `MY_PROXY_API_KEY`). If your agent code already reads different names, edit them directly in the table.

> **Note**: These names are shared across all environments — the platform injects the environment-specific URL and API key values at runtime. Edit only if your code uses different names.

### Step 4: Use the Proxy in Agent Code[​](#step-4-use-the-proxy-in-agent-code "Direct link to Step 4: Use the Proxy in Agent Code")

After saving, the **Environment Variables & Integration Guide** panel opens automatically. It shows the injected variable names (editable here too) and an **Integration Guide** with a ready-to-use Python snippet that loads the MCP tools through the injected proxy URL and API key:

```
import os
from typing import Any
from langchain_mcp_adapters.client import MultiServerMCPClient

raw_urls = os.environ.get("MY_PROXY_URL", "")
mcp_server_urls = [url.strip() for url in raw_urls.split(",") if url.strip()]
mcp_api_key = os.environ.get("MY_PROXY_API_KEY", "").strip()

server_configs: dict[str, dict[str, Any]] = {
    f"mcp_server_{i}": {
        "url": url,
        "transport": "streamable_http",
        "headers": {
            "API-Key": mcp_api_key,
            "Authorization": "",
        },
    }
    for i, url in enumerate(mcp_server_urls)
} if mcp_server_urls and mcp_api_key else {}

mcp_client = MultiServerMCPClient(server_configs)
tools = await mcp_client.get_tools()
```

The variable names in the snippet match whatever you set in Step 3. You can reopen this panel at any time from the MCP configuration detail page by clicking **Environment Variables & Integration Guide** in the top-right corner.

> **Note**: Variable names are shared across all environments. If the agent is in a deployed state, the updated configuration is injected into the running pod automatically — no rebuild or redeploy is required.

***

## Configuring an MCP Proxy for an External Agent[​](#configuring-an-mcp-proxy-for-an-external-agent "Direct link to Configuring an MCP Proxy for an External Agent")

### Step 1: Open the Agent and Add an MCP Configuration[​](#step-1-open-the-agent-and-add-an-mcp-configuration "Direct link to Step 1: Open the Agent and Add an MCP Configuration")

1. Navigate to your project (**Projects** → select project → **Agents**) and open an **External** agent.
2. In the left sidebar, click **Configure**.
3. In the **MCP Configurations** section, click **Add MCP Configuration**.
4. Under **MCP Server**, click **Select an MCP Server**, choose a proxy from the drawer, and click **Save**.

> External agents do not show the **Environment Variable Names** section — the platform provides the connection details directly instead of injecting environment variables.

### Step 2: Connect Your Agent Code to the Proxy[​](#step-2-connect-your-agent-code-to-the-proxy "Direct link to Step 2: Connect Your Agent Code to the Proxy")

After saving, the **Connect to MCP Server** panel opens automatically with everything needed to reach the proxy from your agent code:

| Field            | Description                                                                             |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Endpoint URL** | The gateway invoke URL for this MCP proxy — use it as the server URL in your MCP client |
| **Header Name**  | The HTTP header to pass the API key (default `X-API-Key`)                               |
| **API Key**      | The generated client key — **copy it now**, it will not be shown again                  |
| **Example cURL** | A ready-to-use cURL command combining the Endpoint URL, Header Name, and API Key        |

Example cURL:

```
curl -N <endpoint-url> \
  --header "X-API-Key: <your-api-key>"
```

Configure your agent's MCP client using the Endpoint URL and pass the API Key in the configured header on every request.

You can reopen the connection details panel at any time from the MCP configuration detail page by clicking **Connect to MCP Server** in the top-right corner. However, the API Key is only displayed once at creation time — if lost, delete the configuration and re-add it to generate a new key.

***

## Attaching an MCP Proxy During Agent Creation[​](#attaching-an-mcp-proxy-during-agent-creation "Direct link to Attaching an MCP Proxy During Agent Creation")

You can also attach MCP proxies while creating a new agent, without visiting the Configure page afterward.

1. During agent creation, find the **MCP Proxies (Optional)** section.
2. Click **Add**, then select a proxy from the **Select MCP Proxy** drawer (searchable, with an **Add MCP Proxy** link to register a new one).
3. For each selected proxy, define the **URL variable name** and **API key variable name** (auto-suggested, customizable). Names must match `^[A-Za-z_][A-Za-z0-9_]*$`, be unique across the agent's configuration, and differ from each other.
4. If the agent spans multiple environments, use the per-environment tabs to select a proxy for each environment.

The proxies you attach here appear afterward as MCP configurations on the agent's **Configure** page.

***

## Managing MCP Configurations[​](#managing-mcp-configurations "Direct link to Managing MCP Configurations")

From the **Configure** page, the **MCP Configurations** table shows all attached configurations with:

* **Name**: The configuration name (derived from the linked proxy). Click a row to open the detail page.
* **Description**: The configuration's description.
* **Created**: When the binding was created.
* **Actions**: A delete icon (tooltip *"Remove MCP configuration"*) to detach the proxy. Confirm in the **Remove MCP Configuration** dialog.

Use the **Search by name or description...** box to filter. Multiple configurations can be attached to a single agent, letting the agent code use different MCP servers by referencing their respective environment variable names (platform agents) or endpoint URLs and API keys (external agents).

> To change the linked proxy, remove the configuration and add a new one with the desired proxy.

***

## Notes[​](#notes "Direct link to Notes")

* MCP proxy credentials are **never exposed** to agent code directly — only the injected environment variables (platform agents) or the gateway endpoint + API key (external agents) are available at runtime.
* For platform agents, if the agent is in a deployed state, the updated MCP configuration is injected into the running pod automatically — no rebuild or redeploy is required.
* For external agents, the Endpoint URL routes traffic through the AI Gateway, applying any security, access control, and rewrite rules configured on the proxy.
* The external agent API Key shown after saving is a **one-time display** — it cannot be retrieved again. If lost, delete the MCP configuration and re-add it to generate a new key.
* Each environment uses a separate MCP server mapping; in a multi-environment organization, select a proxy per environment.