docs(sdk): add MCP server env variable resolution for file-based agents

sdk/guides/agent-file-based.mdx

@@ -1,6 +1,6 @@
 ---
 title: File-Based Agents
 description: Define specialized sub-agents as simple Markdown files with YAML frontmatter — no Python code required.
 ---
 
 import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx";
@@ -13,7 +13,7 @@
 
 ## Agent File Format
 
 An agent is a single `.md` file with YAML frontmatter and a Markdown body:
 
 ```markdown icon="markdown"
 ---
@@ -40,9 +40,9 @@
 Keep feedback concise and actionable. For each issue, suggest a fix.
 ```
 
 The YAML frontmatter configures the agent. The Markdown body becomes the agent's system prompt.
 
 ### Frontmatter Fields
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
@@ -166,23 +166,23 @@
 print(f"Registered {len(agent_names)} agents: {agent_names}")
 ```
 
 This scans both project-level and user-level directories, deduplicates by name, and registers each agent as a delegate that can be spawned by the orchestrator.
 
 ## Manual Loading
 
 For more control, load and register agents explicitly:
 
 ```python icon="python" focus={3-6, 8-14}
 from pathlib import Path
 
 from openhands.sdk import load_agents_from_dir, register_agent, agent_definition_to_factory
 
 # Load from a specific directory
 agents_dir = Path("agents")
 agent_definitions = load_agents_from_dir(agents_dir)
 
 # Register each agent
 for agent_def in agent_definitions:
     register_agent(
         name=agent_def.name,
         factory_func=agent_definition_to_factory(agent_def),
@@ -218,7 +218,7 @@
 ```
 
 The factory:
 - Maps tool names from the frontmatter to `Tool` objects
 - Appends the Markdown body to the parent system message via `AgentContext(system_message_suffix=...)`
 - Respects the `model` field (`"inherit"` keeps the parent LLM; an explicit model name creates a copy)
 
@@ -229,8 +229,8 @@
 ```python icon="python" focus={3, 4}
 from openhands.sdk.subagent import load_project_agents, load_user_agents
 
 project_agents = load_project_agents("/path/to/project")
 user_agents = load_user_agents()  # scans ~/.agents/agents/ and ~/.openhands/agents/
 ```
 
 ## Using with Delegation
@@ -344,6 +344,34 @@
 
 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: