Attach or update an agent MCP server
Attach a connector to an agent, or update its settings if it is already attached (upsert).
server_id comes from your MCP catalog (GET /mcp/servers); custom MCP servers you added in Settings are listed there too, keyed by their secret. Identity is taken from the path, so the body carries settings only: which account to use, approval mode, per-tool approvals and tool restrictions.
Attach may succeed before OAuth is completed; auth_status reports 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
Connector settings for PUT /agents/{agent_id}/mcp-servers/{server_id}. Identity comes from the path; unknown keys are dropped.
Response
The attached (or updated) MCP server.
"abc123DEFghiJKL"
The resulting connector entry, 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"
The agent's configuration version after this change.