Attach a local MCP connector
/api/v1/agents/{agent_id}/mcp-attachmentsAttach 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.
Every local call asks a person, so attaching a connector locally 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. Private connectors remain owner-only, including for workspace administrators.
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
uuidHeader 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.
Create one attachment directly in local execution mode.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/mcp-attachments" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "server_id": "00000000-0000-4000-8000-000000000101", "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" } ]}Configure an MCP attachment PATCH
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.
List agents GET
List agents visible to the caller in the active organization. Private agents are visible to their owners and workspace admins; restricted agents are also visible to their grantees. Shared agents are visible to all active members.