Copy page

Version: Next

Configure MCP Proxies for an Agent

Agents can be configured to use one or more MCP Proxies 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

At least one MCP Proxy registered at the org level (see Register an MCP Proxy)
An agent created in a project (Platform-hosted or External)

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

Step 1: Open the Agent

Navigate to your project (Projects → select project → Agents).
Click on a Platform-tagged agent.
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

Open the Tool Configurations tab and click Add Tool Configuration. A right-side drawer opens.
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."
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).
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.)

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

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

Step 1: Open the Agent and Add a Tool Configuration

Navigate to your project (Projects → select project → Agents) and open an External agent.
In the left sidebar, click Configure, then open the Tool Configurations tab.
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

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

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

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

During agent creation, find the MCP Proxies (Optional) section.
Click Add, then select a proxy from the Select MCP Proxy drawer (searchable, with an Add MCP Proxy link to register a new one).
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.
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

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

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.

Prerequisites​

Overview: Agent Types​

Configuring an MCP Proxy for a Platform-Hosted Agent​

Step 1: Open the Agent​

Step 2: Add a Tool Configuration​

Step 3: Set Environment Variable Names​

Step 4: Use the Proxy in Agent Code​

Configuring an MCP Proxy for an External Agent​

Step 1: Open the Agent and Add a Tool Configuration​

Step 2: Manage the Per-Environment API Key​

Step 3: Connect Your Agent Code to the Proxy​

Attaching an MCP Proxy During Agent Creation​

Managing Tool Configurations​

Notes​