Skip to main content
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 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​

  • 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​

TypeDescription
PlatformAgent 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.
ExternalAgent 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​

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​

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​

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

Variable KeyDefault Name (example)Description
urlMY_PROXY_URLBase URL of the MCP server endpoint
apikeyMY_PROXY_API_KEYAPI 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​

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​

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​

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

FieldDescription
Endpoint URLThe gateway invoke URL for this MCP proxy — use it as the server URL in your MCP client
Header NameThe HTTP header to pass the API key (default X-API-Key)
API KeyThe generated client key — copy it now, it will not be shown again
Example cURLA 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​

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​

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​

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