Enhance MCP server configuration by adding support for optional bearer tokens in README.md and example YAML files. Update schema to include bearer_token field and modify MCP client to utilize bearer tokens for authentication. Add tests for environment variable substitution of bearer tokens in configuration.

Author: stormaref

README.md

@@ -301,7 +301,8 @@ Copy [config/agents.example.yaml](config/agents.example.yaml) as a starting poin
 | `mcp_servers`           | List of remote MCP servers (`transport` must be `streamable_http`)                           |
 | `mcp_servers[].name`    | Short name used in qualified tool names (`name.tool`)                                        |
 | `mcp_servers[].url`     | Streamable HTTP MCP endpoint (must end with `/mcp` for standard layouts)                     |
-| `mcp_servers[].headers` | Optional HTTP headers (for example auth tokens)                                              |
+| `mcp_servers[].bearer_token` | Optional bearer token; sent as `Authorization: Bearer ...` (supports `${ENV_VAR}`)      |
+| `mcp_servers[].headers` | Optional extra HTTP headers merged with bearer auth                                          |
 | `tool_allowlist`        | Optional list of `server.tool` names; omit to allow all tools from connected servers         |
 
 Environment variable substitution supports `${VAR}` and `${VAR:-default}`. If `VAR` is unset and no default is provided, startup fails with a clear error.
@@ -339,6 +340,12 @@ mcp_servers:
   - name: my_api
     transport: streamable_http
     url: https://mcp.example.com/mcp
+    bearer_token: ${MY_MCP_TOKEN}
+```
+
+You can also set auth manually via `headers`:
+
+```yaml
     headers:
       Authorization: "Bearer ${MY_MCP_TOKEN}"
 ```

config/agents.example.yaml

@@ -15,6 +15,7 @@ agents:
       - name: search
         transport: streamable_http
         url: http://search-mcp:8002/mcp
+        bearer_token: ${SEARCH_MCP_TOKEN}
     tool_allowlist:
       - filesystem.read_file
       - search.web_search

src/sub_agent_mcp/config/schema.py

@@ -32,6 +32,7 @@ class MCPServerConfig(BaseModel):
     name: str = Field(min_length=1)
     transport: Literal["streamable_http"]
     url: HttpUrl
+    bearer_token: SecretStr | None = None
     headers: dict[str, str] = Field(default_factory=dict)
 
 

src/sub_agent_mcp/mcp_client/headers.py

@@ -0,0 +1,15 @@
+"""HTTP header resolution for downstream MCP server connections."""
+
+from __future__ import annotations
+
+from sub_agent_mcp.config.schema import MCPServerConfig
+
+
+def resolve_mcp_server_headers(server: MCPServerConfig) -> dict[str, str] | None:
+    """Build request headers for a downstream MCP server, or None when no auth is configured."""
+    headers = dict(server.headers)
+    if server.bearer_token is not None:
+        token = server.bearer_token.get_secret_value()
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+    return headers or None

src/sub_agent_mcp/mcp_client/manager.py

@@ -9,6 +9,7 @@
 from sub_agent_mcp.agent.errors import MCPConnectionError
 from sub_agent_mcp.config.schema import AgentConfig
 from sub_agent_mcp.logging import get_logger
+from sub_agent_mcp.mcp_client.headers import resolve_mcp_server_headers
 from sub_agent_mcp.mcp_client.tool_registry import allows_all_tools, qualified_tool_name
 
 if TYPE_CHECKING:
@@ -26,7 +27,11 @@ def build_client_config(agent: AgentConfig) -> dict[str, dict[str, Any]]:
         server.name: {
             "transport": "streamable_http",
             "url": str(server.url),
-            "headers": server.headers,
+            **(
+                {"headers": headers}
+                if (headers := resolve_mcp_server_headers(server)) is not None
+                else {}
+            ),
             "timeout": timeout,
         }
         for server in agent.mcp_servers

src/sub_agent_mcp/mcp_client/tool_registry.py

@@ -7,10 +7,12 @@
 
 from mcp import ClientSession
 from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import create_mcp_http_client
 
 from sub_agent_mcp.agent.errors import MCPConnectionError
 from sub_agent_mcp.config.schema import AgentConfig
 from sub_agent_mcp.logging import get_logger
+from sub_agent_mcp.mcp_client.headers import resolve_mcp_server_headers
 
 logger = get_logger(__name__)
 
@@ -86,26 +88,31 @@ async def discover_tools(agent: AgentConfig) -> list[ToolMetadata]:
 
     for server in agent.mcp_servers:
         try:
-            async with streamable_http_client(str(server.url)) as (read, write, _):
-                async with ClientSession(read, write) as session:
-                    await session.initialize()
-                    result = await session.list_tools()
-                    for tool in result.tools:
-                        if not is_tool_allowed(server.name, tool.name, agent.tool_allowlist):
-                            continue
-
-                        schema = tool.inputSchema if hasattr(tool, "inputSchema") else None
-                        if not validate_tool_schema(tool.name, tool.description, schema):
-                            continue
-
-                        discovered.append(
-                            ToolMetadata(
-                                name=tool.name,
-                                server=server.name,
-                                description=tool.description or "",
-                                qualified_name=qualified_tool_name(server.name, tool.name),
+            headers = resolve_mcp_server_headers(server)
+            async with create_mcp_http_client(headers=headers) as http_client:
+                async with streamable_http_client(
+                    str(server.url),
+                    http_client=http_client,
+                ) as (read, write, _):
+                    async with ClientSession(read, write) as session:
+                        await session.initialize()
+                        result = await session.list_tools()
+                        for tool in result.tools:
+                            if not is_tool_allowed(server.name, tool.name, agent.tool_allowlist):
+                                continue
+
+                            schema = tool.inputSchema if hasattr(tool, "inputSchema") else None
+                            if not validate_tool_schema(tool.name, tool.description, schema):
+                                continue
+
+                            discovered.append(
+                                ToolMetadata(
+                                    name=tool.name,
+                                    server=server.name,
+                                    description=tool.description or "",
+                                    qualified_name=qualified_tool_name(server.name, tool.name),
+                                )
                             )
-                        )
         except Exception as exc:
             logger.error(
                 "mcp_server_unreachable",

tests/test_config.py

@@ -132,6 +132,27 @@ def test_invalid_agent_id(tmp_path: Path) -> None:
         load_agents_config(config_file)
 
 
+def test_load_config_with_bearer_token_env_substitution(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_file = tmp_path / "agents.yaml"
+    config_file.write_text(
+        VALID_YAML.replace(
+            "url: http://filesystem-mcp:8001/mcp",
+            "url: http://filesystem-mcp:8001/mcp\n        bearer_token: ${MCP_TOKEN}",
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("MCP_TOKEN", "downstream-secret")
+
+    config = load_agents_config(config_file)
+
+    assert (
+        config.agents[0].mcp_servers[0].bearer_token.get_secret_value()  # type: ignore[union-attr]
+        == "downstream-secret"
+    )
+
+
 def test_load_config_without_tool_allowlist(tmp_path: Path) -> None:
     """Omitting tool_allowlist from YAML allows all tools."""
     yaml_without_allowlist = """

tests/test_mcp_headers.py

@@ -0,0 +1,111 @@
+"""Tests for downstream MCP server header resolution."""
+
+from __future__ import annotations
+
+from pydantic import SecretStr
+
+from sub_agent_mcp.config.schema import AgentConfig, LLMConfig, MCPServerConfig
+from sub_agent_mcp.mcp_client.headers import resolve_mcp_server_headers
+from sub_agent_mcp.mcp_client.manager import build_client_config
+
+
+def test_resolve_mcp_server_headers_bearer_token() -> None:
+    server = MCPServerConfig(
+        name="api",
+        transport="streamable_http",
+        url="https://mcp.example.com/mcp",
+        bearer_token=SecretStr("secret-token"),
+    )
+
+    headers = resolve_mcp_server_headers(server)
+
+    assert headers == {"Authorization": "Bearer secret-token"}
+
+
+def test_resolve_mcp_server_headers_merges_custom_headers() -> None:
+    server = MCPServerConfig(
+        name="api",
+        transport="streamable_http",
+        url="https://mcp.example.com/mcp",
+        bearer_token=SecretStr("secret-token"),
+        headers={"X-Custom": "value"},
+    )
+
+    headers = resolve_mcp_server_headers(server)
+
+    assert headers == {
+        "Authorization": "Bearer secret-token",
+        "X-Custom": "value",
+    }
+
+
+def test_resolve_mcp_server_headers_without_bearer_token() -> None:
+    server = MCPServerConfig(
+        name="api",
+        transport="streamable_http",
+        url="https://mcp.example.com/mcp",
+    )
+
+    assert resolve_mcp_server_headers(server) is None
+
+
+def test_resolve_mcp_server_headers_empty_bearer_token() -> None:
+    server = MCPServerConfig(
+        name="api",
+        transport="streamable_http",
+        url="https://mcp.example.com/mcp",
+        bearer_token=SecretStr(""),
+    )
+
+    assert resolve_mcp_server_headers(server) is None
+
+
+def test_build_client_config_omits_headers_without_bearer_token() -> None:
+    agent = AgentConfig(
+        id="researcher",
+        title="Research Agent",
+        description="Test agent",
+        llm=LLMConfig(
+            base_uri="https://api.openai.com/v1",
+            api_key=SecretStr("llm-key"),
+            model_id="gpt-4.1-mini",
+        ),
+        system_prompt="You are helpful.",
+        mcp_servers=[
+            MCPServerConfig(
+                name="api",
+                transport="streamable_http",
+                url="https://mcp.example.com/mcp",
+            )
+        ],
+    )
+
+    config = build_client_config(agent)
+
+    assert "headers" not in config["api"]
+
+
+def test_build_client_config_includes_bearer_token() -> None:
+    agent = AgentConfig(
+        id="researcher",
+        title="Research Agent",
+        description="Test agent",
+        llm=LLMConfig(
+            base_uri="https://api.openai.com/v1",
+            api_key=SecretStr("llm-key"),
+            model_id="gpt-4.1-mini",
+        ),
+        system_prompt="You are helpful.",
+        mcp_servers=[
+            MCPServerConfig(
+                name="api",
+                transport="streamable_http",
+                url="https://mcp.example.com/mcp",
+                bearer_token=SecretStr("mcp-token"),
+            )
+        ],
+    )
+
+    config = build_client_config(agent)
+
+    assert config["api"]["headers"] == {"Authorization": "Bearer mcp-token"}