Attach or update an agent MCP server
Attach an MCP server (connector) to an agent, or update its configuration if it’s already attached (upsert).
The server_id is validated against the caller’s MCP catalog. Catalog identity fields (type, server_id, secret_id, mcp_server_url) always come from the catalog and cannot be spoofed via the request body — the body carries only free-form connector configuration (e.g. approval mode, tool restrictions); any identity keys in it are ignored.
Attach may succeed before OAuth is completed; auth_status reflects the catalog’s authentication state.
Authorizations
Path Parameters
ID of the agent. Also accepts the reserved aliases gumball and analytics.
ID of the MCP server from the caller's catalog.
Body
Free-form connector configuration. Identity keys are catalog-derived and ignored.
Response
The attached (or updated) MCP server.
"abc123DEFghiJKL"
The resulting MCP server tool config, with secrets and server URL redacted.
true if the server was newly attached; false if an existing attachment was updated.
true
Catalog authentication status for the server (e.g. whether OAuth has been completed).
"authenticated"
