feat(mcp): reach external MCP servers over HTTP, and resolve ${VAR} secrets from the environment

[antiv]

MATE serves its own agents as HTTP MCP servers, but the client could only speak stdio. A remote server therefore had to be reached by spawning npx mcp-remote as a subprocess — Node on the host, a process per server, and a translation hop to talk a protocol MATE already implements on the other side.

Two commits, reviewable separately.

1. HTTP/SSE transport for the MCP client

A server entry is now HTTP when it carries a url, and stdio when it carries command/args. Streamable HTTP is the default transport, with sse selectable for older servers; headers carries auth.

ADK 2.3 already ships StreamableHTTPConnectionParams and SseConnectionParams, so this is wiring rather than protocol work.

Decisions worth a look:

• timeout keeps the meaning it already has for stdio — how long a slow tool may take — so it maps to the read timeout, not ADK's 5-second connect timeout. Otherwise every config that raised timeout to 300 for a slow tool would silently have started meaning something else. connect_timeout is separate.
• A url that is not http or https is refused rather than handed to the transport.
• If an entry sets both forms, the url wins and the command is ignored, with a warning — rather than silently spawning a subprocess nobody asked for.

The three config fields that may arrive parsed or as a JSON string were handling that inline; headers would have been a fourth copy, so the parsing moved into one helper.

2. ${VAR} interpolation, and the deprecated class name

The MCP config modal has been telling users to write secrets as ${AUTH_HEADER} while no such substitution existed anywhere in the tree. Anyone who followed the hint sent the literal thirteen-character string as their credential and got an authentication failure with nothing to explain it.

Any string value in a server entry — headers, url, command, args, env — may now reference the server environment as ${VAR}, so credentials stay out of the agents_config row and out of config exports.

Judgement calls, flagged because they are choices rather than obvious:

• An unset variable skips that server and logs which names were missing. An empty substitution sends an unauthenticated request that may quietly succeed with reduced scope; leaving the placeholder sends ${VAR} itself as the credential, which is the bug being fixed. Skipping is the only failure that is loud.
• Set-but-empty is a real value, not a miss — something deliberately set it.
• Interpolation runs after JSON parsing, not over raw config text, so a secret containing a quote cannot corrupt a field that arrived as a JSON string.

Only ${NAME} is a placeholder; a bare $HOME is left alone.

Note recorded in the docs: interpolation reads the server's environment, so anyone who can edit an agent's MCP config can route an environment value into a URL they choose. That is the same trust level agent configuration already carries — an admin can enable code_executor — so it is not a new exposure, but it is now written down rather than implicit.

MCPToolset is also renamed to McpToolset. ADK 2.3 keeps the old name as a subclass that only warns and delegates, so this is behaviour-identical and silences the DeprecationWarning. Four remaining mentions are prose in comments in unrelated modules and are left alone.

UI and docs

The dashboard's MCP config is a free JSON textarea, so it needed no new form — only its placeholder, which taught the mcp-remote workaround as the default example. documents/MCP_SERVERS.md gains a transport table, the HTTP field reference, and an interpolation section.

Verification

799 tests, OK.

Each change was checked by reverting it and confirming the new tests fail:

Reverted	Result
HTTP transport	9 of 13 fail; the 4 that pass are the stdio regression guards
Interpolation	8 of 10 fail; the 2 that pass assert literal config and bare $NAME are untouched

The stdio path is covered by explicit regression tests — it is what every existing installation is configured with, and it is unchanged.

Not covered: no test talks to a real MCP server over the network. The self-referential end-to-end check — pointing MATE at its own /agents/{name}/mcp endpoint — is worth doing once against a running instance before this is relied on in production.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01ToCUNy2SqwvfTq4a6xfSk1

---

Generated by Claude Code