v1

latestOpenAPI 3.0.02026-07-26492143.5 KB

Agents

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.

put/agents/{agent_id}/mcp-servers/{server_id}

Path parameters

agent_idstring required

ID of the agent.

server_idstring required

ID of the MCP server from the caller's catalog.

Request body

object required

Free-form connector configuration. Identity keys are catalog-derived and ignored.

Response

The attached (or updated) MCP server.

agent_idstring

mcp_serverobject

The resulting MCP server tool config, with secrets and server URL redacted.

createdboolean

true if the server was newly attached; false if an existing attachment was updated.

auth_statusstring nullable

Catalog authentication status for the server (e.g. whether OAuth has been completed).

Example response

{
  "agent_id": "abc123DEFghiJKL",
  "created": true,
  "auth_status": "authenticated"
}

All 49 operations