Skip to main content
Agent Client has a portable MCP layer. You define MCP servers once, the Client chooses which ones a request gets, and each provider translates the chosen definitions into its own CLI’s MCP configuration or refuses them. The catalog, Client defaults and per-request names have shipped since well before 0.32.0.
Facts on this page are marked apart. Released means in 0.32.0 on Maven Central. On main, not yet released means 0.32.1-SNAPSHOT, checked against agent-client main b35143af: resolve it from https://central.sonatype.com/repository/maven-snapshots/ with snapshots enabled. None of the main-only behaviour is in 0.32.0. See Using development snapshots from main for pinning one build and reading its provenance.

Source on GitHub main

docs/examples/howto/McpServers.java, compiled and run by the agent-client build

Define the servers

Released in 0.32.0. Load a catalog from a file, or from a directory of *.json files, in the common "mcpServers" format. A server without a type is stdio. ${NAME} values expand from the environment:
Or build the same catalog in code. A server is a StdioDefinition, an SseDefinition or an HttpDefinition:

Choose servers on the Client and per request

Released in 0.32.0. Register the catalog on the Client and name the default servers every request gets:
A request adds servers by name. They join the defaults rather than replacing them:
A name missing from the catalog fails with IllegalArgumentException before the provider is called. Naming servers without registering a catalog fails with IllegalStateException.

What each provider does

Gemini on 0.32.0 and earlier: do not configure MCP servers for Gemini in a workspace that has its own .gemini/settings.json. Client replaces that file for the run and deletes it afterwards. The fix is on main, not yet released.
The lifecycle providers are part of the asynchronous lifecycle, which is itself on main only.

A scoped MCP binding for a retained session

On main, not yet released (0.32.1-SNAPSHOT). A retained lifecycle session can freeze one MCP server slot and an environment when it is created, with SessionSpec.binding(new ConnectionBinding(name, definition, environment)). A later request can replace the slot’s definition with refreshBinding(replacement), under the same slot name and environment; the provider reconnects under that request’s execution. A replacement that changes the slot name or the environment is rejected. Only the Claude Code lifecycle provider implements refresh today. The full class is McpServers.java. The build compiles it and runs it against a recording stand-in that shows which definitions reach the provider (agent-client-tutorials, McpServersTest). The ACP translation is covered by AcpMcpServersTests, which runs an offline ACP agent fixture.