MCP servers | AX Documentation

mcp_servers exposes MCP servers to the agent for variants that use this setup. Use this field when the product surface or environment includes an MCP tool.

mcp_servers:
  - name: fixture-sentinel
    type: stdio
    command: /workspace/fixture-mcp.py
    args: []
  - name: ax
    type: http
    url: http://localhost:3001/mcp

MCP server object

An MCP server object defines one server and its transport. The required connection fields depend on type.

Field	Required	Type / values	Notes
`name`	Yes	String	Must be unique within the setup's `mcp_servers`.
`type`	Yes	`stdio`, `http`, or `sse`	Transport.
`command`	For `stdio`	String	Executable path or command inside the sandbox.
`args`	No	String list	Stdio command arguments.
`url`	For `http` / `sse`	String	MCP endpoint URL.
`env`	No	MCP stdio env entries	Only valid for `stdio`.
`headers`	No	MCP header entries	Only valid for `http` / `sse`.

Transport-specific rules:

stdio uses command, optional args, and optional env.
http and sse use url and optional headers.
Mixing stdio-only and endpoint-only fields is rejected.

MCP stdio env entry

env forwards declared environment values to a stdio MCP process. Each entry is either a bare name or an object:

env:
  - GITHUB_TOKEN
  - name: GH_AUTH
    from: GITHUB_TOKEN
  # Managed model access for an LLM-backed MCP server (no raw provider key):
  - name: ANTHROPIC_API_KEY
    from: AXP_MODEL_PROXY_TOKEN
  - name: ANTHROPIC_BASE_URL
    from: AXP_MODEL_PROXY_URL

Field	Required	Type / values	Notes
`name`	Yes	String	Env var name as seen by the MCP server process.
`from`	Yes	Env name or virtual ref	Declared `environment_variables` name, or a managed-proxy virtual ref (`AXP_MODEL_PROXY_TOKEN` / `AXP_MODEL_PROXY_URL`).

AXP_MODEL_PROXY_TOKEN and AXP_MODEL_PROXY_URL are virtual references to the run's workload token and Anthropic-style proxy base URL. They resolve only when the run has managed model access (ax experiment run, or default ax experiment run --local / ax local run; not with --local-model-keys); without it they are dropped with a warning. They are not org secret-store slugs and are not organization BYOK configuration — see Model Providers and the 514.ax AI Gateway.

MCP HTTP and SSE header object

headers attaches HTTP headers to an http or sse MCP server. Use placeholders when a header needs a declared secret value.

headers:
  - name: Authorization
    value: "Bearer ${SUPABASE_SERVICE_ROLE_KEY}"

Field	Required	Type / values	Notes
`name`	Yes	String	HTTP header name. Header names must be unique per server, case-insensitively.
`value`	Yes	String	May contain `${SECRET_NAME}` placeholders. Bare `$NAME` is literal.

MCP env entries and header placeholders reference environment variable names visible to the variant. Values can come from literal environment_variables, ax://secrets/<slug> references, or (stdio env only) the managed-proxy virtual refs AXP_MODEL_PROXY_TOKEN / AXP_MODEL_PROXY_URL.

Rules enforced at ax experiment validate time:

Every stdio env[*].from and every ${NAME} placeholder in a header value must reference a name visible to the variant, or (stdio env only) a managed-proxy virtual ref.
Bare $NAME is treated as a literal; only ${NAME} is a placeholder.
HTTP header names are unique per server, case-insensitively.
command / args / env are only valid for type: stdio; url / headers are only valid for type: http / sse.

Resolved secret values are written into the agent session frame and can appear in run artifacts. Treat artifacts as sensitive whenever an experiment forwards secrets to MCP servers.

Search documentation

MCP server object

MCP stdio env entry

MCP HTTP and SSE header object