Guest Machines
API referenceConnectors

List synchronized MCP tools

GET/api/v1/mcp-servers/{server_id}/tools

List sanitized tool definitions from one immutable catalog. Omit catalog_version to select the newest version; a returned cursor continues that exact version.

Required access

Credentials: 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: mcp_servers:read

Uses ordinary connector visibility. Private connector catalogs are visible only to their owner or an organization administrator.

Authorization

AuthorizationBearer <token>

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

server_id*Server Id
Formatuuid

Query Parameters

catalog_version?|null
cursor?|null
limit?Limit
Range1 <= value <= 100
Default50

Header Parameters

X-Org-Id?|

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/mcp-servers/497f6eca-6276-4993-bfeb-53cbbbba6f08/tools" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"
{  "catalog": {    "server_id": "820efca4-4a15-4ab7-82fc-9e76f6d61325",    "version": 1,    "server_behavior_version": 1,    "protocol_version": "string",    "catalog_digest": "string",    "tool_count": 0,    "cache_hints": [],    "synced_at": "2019-08-24T14:15:22Z"  },  "tools": [    {      "name": "string",      "description": "string",      "input_schema": {},      "output_schema": {},      "annotations": {        "title": "string",        "read_only_hint": true,        "destructive_hint": true,        "idempotent_hint": true,        "open_world_hint": true      },      "schema_digest": "string",      "tool_digest": "string"    }  ],  "next_cursor": "string",  "has_more": true}

Synchronize MCP tools POST

Connect to the saved Streamable HTTP endpoint and record a new immutable catalog only when every returned tool definition is valid. Existing agent attachments keep their selected catalog until explicitly changed.

Start an approved private API task POST

Start a fixed task reviewed by its owner under Triggers > Private API Tasks. Only request_id is accepted; the input, agent, app grants, per-run budgets and hourly limit are frozen. Reuse the same UUID when retrying a request to recover its original run. One active or paused run blocks additional starts. Results and approvals remain owner-private; run_url links to the owner's run page.