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 buildDefine 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:
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:IllegalArgumentException before the provider is called. Naming
servers without registering a catalog fails with IllegalStateException.
What each provider does
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.