Configure an MCP attachment
/api/v1/agents/{agent_id}/mcp-attachments/{attachment_id}Choose provider-hosted execution or select an exact synchronized catalog and explicit tool grant for local execution. Supply expected_attachment_behavior_version; a stale version returns 409 and makes no change.
Every local call asks a person, so making an attachment local can leave schedules and inbound webhooks that ran the agent unable to run it. The response lists them in broken_triggers; they stay on until someone turns them off.
Required access
Credentials: automation account, delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: agents:edit, mcp_servers:read
The caller needs edit authority for the agent and read authority for the connector. Automation accounts may configure only shared agents and connectors within their scoped authority.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Path Parameters
uuiduuidHeader Parameters
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
New connector execution settings and the version being replaced.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/mcp-attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_attachment_behavior_version": 1, "execution_mode": "local", "catalog_version": 1, "tool_grant": [ "get_service", "search_incidents" ] }'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "server_id": "820efca4-4a15-4ab7-82fc-9e76f6d61325", "execution_mode": "local", "attachment_behavior_version": 1, "catalog_version": 1, "tool_grant": [ "string" ], "effective_tool_count": 0, "broken_triggers": [ { "kind": "schedule", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe", "name": "string", "reason": "string" } ]}Retrieve an MCP attachment GET
Read whether one attached connector uses provider-hosted or local execution, the version needed to update its configuration, and the selected local catalog and allowed tools when applicable.
Attach a local MCP connector POST
Attach a synchronized connector directly in local execution mode. This path does not require the selected model to support a hosted MCP connector; it uses that model's registered function-tool encoder.