# Configure MCP Proxies for an Agent

Agents can be configured to use one or more [MCP Proxies](/agent-manager/docs/v1.0.0-alpha1/tutorials/register-mcp-proxy/.md) registered at the organization level. Each binding — called a **tool configuration** — references an org-level MCP proxy and exposes the proxy's per-environment endpoint (and, where required, an API key) to the agent. The process differs slightly between **Platform-hosted** and **External** agents, but both follow the same pattern: reference an org-level proxy from the agent.

The agent does not embed the proxy. It references it, and the platform resolves the proxy's endpoint for the agent's target environment at deploy time. Because the org-level proxy owns its per-environment gateway artifacts, changing the proxy does not redeploy the agent automatically — the agent picks up any change on its next deployment.

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

* At least one MCP Proxy registered at the org level (see [Register an MCP Proxy](/agent-manager/docs/v1.0.0-alpha1/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, with environment-specific values at runtime. |
| **External** | Agent is deployed and managed externally. The platform provides the gateway endpoint URL and a per-environment 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**.

The **Configure** page has two tabs — **LLM Configurations** and **Tool Configurations**. MCP proxies are attached under **Tool Configurations**.

### Step 2: Add a Tool Configuration[​](#step-2-add-a-tool-configuration "Direct link to Step 2: Add a Tool Configuration")

1. Open the **Tool Configurations** tab and click **Add Tool Configuration**. A right-side drawer opens.

2. **Choose the MCP server for this agent.** The drawer lists all org-level MCP proxies. Use the **Search MCP servers** box to filter, then click the server you want.
   <!-- -->
   * If none are listed, the drawer shows *"No MCP servers available"* with a link to *"Add MCP servers from the organization MCP Proxies page first."*

3. The drawer switches to the configuration step, showing:

   <!-- -->

   * The selected **MCP Server** (click the card to change it).
   * A **Configuration Name** (auto-suggested from the proxy name; editable — placeholder `my-mcp-configuration`).
   * The **Environment Variable Names** section (platform agents only, see Step 3).

4. Click **Save**.

> **One proxy, all environments.** Selecting a proxy here is environment-agnostic: the configuration maps every environment in the agent's deployment pipeline to the same proxy. The proxy supplies each environment's endpoint, and the platform injects environment-specific values at runtime — empty in any environment the proxy is not configured for. (To choose a *different* proxy per environment, do so while creating the agent — see [Attaching an MCP Proxy During Agent Creation](#attaching-an-mcp-proxy-during-agent-creation).)

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

For platform agents, the drawer shows the **Environment Variable Names** section — the two environment variables the platform injects 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.

> These names are shared across all environments. The platform injects the MCP server URL and API key **values** at runtime per environment (empty in environments the proxy is not configured for). 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, open the tool configuration's detail page and click **Environment Variables & Integration Guide** (top-right). The panel 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.

> Renaming the variables here only changes their names — *"These variable names are injected into the agent at runtime with environment-specific values. Rename them here if your code already uses different names, then save."*

***

## 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 a Tool Configuration[​](#step-1-open-the-agent-and-add-a-tool-configuration "Direct link to Step 1: Open the Agent and Add a Tool Configuration")

1. Navigate to your project (**Projects** → select project → **Agents**) and open an **External** agent.
2. In the left sidebar, click **Configure**, then open the **Tool Configurations** tab.
3. Click **Add Tool Configuration**, choose an MCP server from the drawer, give the configuration a name, 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: Manage the Per-Environment API Key[​](#step-2-manage-the-per-environment-api-key "Direct link to Step 2: Manage the Per-Environment API Key")

Open the tool configuration's detail page. For external agents it shows an **Environment** selector and an **API key** section for the selected environment:

* *"Generate an API key to authenticate this agent's requests to the MCP server through the gateway. Only one key can exist per configuration."*
* Use the controls to **generate**, **regenerate** (rotate), or **delete** (revoke) the key. There is one key per configuration per environment.

Switch environments with the selector to manage each environment's key independently.

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

Click **Connect to MCP Server** (top-right) to open the connection panel for the selected environment:

| Field            | Description                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Endpoint URL** | The gateway invoke URL for this MCP proxy in the selected environment — use it as the server URL in your MCP client |
| **Header Name**  | The HTTP header to pass the API key (from the proxy's Security settings; default `X-API-Key`)                       |
| **API Key**      | The generated client key — shown only right after you generate or rotate it                                         |
| **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>"
```

> When a key is freshly generated, the panel warns *"Make sure to copy your API key now. You will not be able to see it again."* If you reopen the panel later, it shows *"The endpoint is available below. If the MCP server requires an API key, the key was only displayed when this configuration was created."* — rotate the key from the API key section to obtain a new value.

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

***

## 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. (Unlike the Configure page — which attaches one proxy across all environments — agent creation lets you pick a different proxy per environment.)

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

***

## Managing Tool Configurations[​](#managing-tool-configurations "Direct link to Managing Tool Configurations")

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

* **Name**: The configuration name. 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 tool configuration"*) to detach the proxy. Confirm in the **Remove Tool 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, the MCP server URL and API key values are injected at deploy time per environment, and are empty in any environment the proxy is not configured for. Changing the org-level proxy does not redeploy the agent automatically — the agent resolves the endpoint on its next deployment.
* For external agents, the Endpoint URL routes traffic through the AI Gateway, applying any security, access control, and rewrite rules configured on the proxy for that environment.
* The external agent API Key is displayed only right after it is generated or rotated. If lost, rotate the key from the tool configuration's API key section (per environment) to obtain a new value.
* A single proxy attached from the Configure page maps to every environment in the agent's pipeline; the proxy supplies each environment's endpoint. To use different proxies per environment, attach them during agent creation.