From 3107ad1f486e3a7aecfd9ab8f72c85cc304ed178 Mon Sep 17 00:00:00 2001 From: VascoSch92 Date: Wed, 25 Mar 2026 18:52:35 +0100 Subject: [PATCH] update mcp env variables --- sdk/guides/agent-file-based.mdx | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/sdk/guides/agent-file-based.mdx b/sdk/guides/agent-file-based.mdx index 2ce362e4..906299d8 100644 --- a/sdk/guides/agent-file-based.mdx +++ b/sdk/guides/agent-file-based.mdx @@ -344,6 +344,34 @@ Use the fetch tool to retrieve web content and save findings to files. The `mcp_servers` field uses the same format as the [MCP configuration](/sdk/guides/mcp) — each key is a server name, and the value contains `command` and `args` for launching the server. +#### Environment Variable Resolution + +All string values in MCP server configurations support `${VAR}` (and `$VAR`) environment variable references, which are resolved from `os.environ` at load time. This lets you forward secrets and dynamic paths without hard-coding them in Markdown: + +```markdown icon="markdown" +--- +name: api-agent +description: Agent with MCP server using environment-based secrets. +mcp_servers: + my-server: + command: ${PLUGIN_ROOT}/bin/server + args: + - --config + - ${PLUGIN_ROOT}/config.json + env: + API_KEY: ${MY_API_KEY} + remote: + type: http + url: ${API_BASE}/mcp + headers: + Authorization: Bearer ${AUTH_TOKEN} +--- + +An agent that connects to MCP servers configured via environment variables. +``` + +Environment variable resolution applies recursively to all string fields — `command`, `args`, `url`, `headers`, `env`, and any other string values in the server config. If a referenced variable is not set, the placeholder is left unchanged (e.g., `${NONEXISTENT_VAR}` stays as-is). + ### Hooks File-based agents can define [lifecycle hooks](/sdk/guides/hooks) that run at specific points during execution: