gateway

Server path: /gateway | Type: Embedded | PCID required: No

Tools

Tool	Description
`agent_invoke`	Invoke an agent and get its response. MODES: - Default (synchronous): waits for the agent and returns its response. Best for short tasks. If a run exceeds ~50s it does not block or error — it returns an operationId to poll with agent_status, exactly as fire-and-return does. - Fire-and-return (pass async: true): returns an operationId immediately without waiting. Then poll agent_status with that operationId (~5-10s interval) until status is COMPLETE (result included) or FAILED. Use this for long-running agents so you are not blocked waiting.
`agent_status`	Get the status (and, when COMPLETE, the response) of an agent run. Pass the `operationId` returned by a fire-and-return agent_invoke. Returns RUNNING while in progress; COMPLETE with the agent response; or FAILED with the error.
`capabilities_discover`	Discover available capabilities for a task. Returns lightweight recommendations for tools, agent skills, connections, and/or resources — and, opt-in, invocable workflows and agents. Call capability_details to get full details for selected items. Use the “types” parameter to filter by capability type. GATEWAY USAGE: - To find available connections and their PCIDs: call with types: [“connection”] and a request describing the service (e.g., “gmail connections”). - To find available tools: call with types: [“tool”] and a request describing what you want to do. - To discover invocable workflows/agents (OPT-IN — off by default): call with types: [“workflow”, “agent”]. Each result carries its invoke handle (automationId / agentId); invoke them via workflow_invoke / agent_invoke. - Returns IDs inline for every recommended item (PCIDs for connections, collectionIds for resources) — you do NOT need to call gateway_list_workspace afterward to get IDs. - If the response includes `alternativesAvailable` (e.g., `{"gmail": 2}`), the user has multiple connections for that service and only one was picked. Call gateway_list_workspace to see all options when the user needs to choose.
`capability_details`	Get the full details of capabilities returned by capabilities_discover — pass the exact names/ids from that response. For a tool: its complete input and output JSON Schema. For a workflow: its input schema (read this before workflow_invoke). For an agent: its description and output contract (read this before agent_invoke). For a connection or resource: its metadata. Use the “types” parameter to filter which kinds you want details for.
`code-execution_execute`	Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers. Available globals: - callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context. - codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns { success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use gateway_write_artifact. - codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns { success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use gateway_read_artifact after code execution returns. - console.log/error/warn(…args) — Captured to logs array returned in the response. - setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution). EXAMPLES: // Call MCP tools (DO NOT pass PCID - connection is auto-injected from selection context): const emails = await callTool(“gmail”, “gmail_search_emails”, { query: “is:unread” }); // Create output files: const csv = emails.map(e => `${e.from},${e.subject}`).join(‘\n’); await codeExec.createArtifact(‘emails.csv’, csv, ‘csv’); // Read an artifact from the conversation: const data = await codeExec.readArtifact(‘file_abc123’); console.log(data.content); // Return result to agent: return { count: emails.length }; LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read_artifact to access the full result. IMPORTANT — NO UNBOUNDED LOOPS: - NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout. - If a tool doesn’t have a pagination parameter (e.g. “page”), do NOT attempt manual pagination — you will get the same page repeatedly. - If you need more data than one API call returns, return what you have and tell the user the tool’s page limit was reached. - Bounded loops (e.g. for(let i=0; i<items.length; i++)) over local data are fine. - Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total. Default timeout: 10 minutes (max 15 minutes). GATEWAY CONNECTION HANDLING: Connections are auto-injected for all callTool() calls inside the sandbox — do NOT put PCIDs in the code. - If the user has one connection per service, it is used automatically. - If the user has multiple connections for the same service, use the connectionSelections parameter to specify which one: {“gmail”: “<pcid>”}. Obtain PCIDs via capabilities_discover with types: [“connection”]. - callTool(server, tool, args) uses the same server identifiers as gateway_invoke (from capability_details), e.g. “gmail”, “dynamic/<id>”, “remote/<id>”. - When connectionSelections is omitted, the first connection per service is used as default.
`gateway_invoke`	Invoke a single MCP tool on a registered server. Good for simple, one-shot tool calls. NOTE: Results are returned in full (not truncated). This is fine for most calls, but if a tool is likely to return a large amount of data (e.g., searching hundreds of emails, bulk exports, large query results), prefer code-execution_execute instead — it automatically saves large results as artifacts. CONNECTION HANDLING: - Connections are auto-injected. If the user has one connection for a service (e.g., one Gmail account), it is used automatically — do NOT pass PCID. - If the user has MULTIPLE connections for the same service, pass a PCID (Pinkfish Connection ID) to select which one. Discover available connections and their PCIDs via capabilities_discover with types: [“connection”]. - Do NOT pass PCID in the “arguments” object — use the top-level PCID parameter instead. For complex multi-step operations, data processing, file creation, or tool calls expected to return large results, use code-execution_execute instead.
`gateway_list_artifacts`	List the files in a storage container. Returns each file’s name, id, size, MIME type and creation date — use this to find a file’s id before gateway_read_artifact.
`gateway_list_workspace`	List everything in the user’s workspace: connections, resources (datastores, filestores, knowledge bases, vaults), and invocable workflows + agents. Returns every item with its ID (PCID for connections, collectionId for resources, automationId for workflows, agentId for agents) and name. Prefer `capabilities_discover` for task-relevant work — that tool returns IDs inline for recommended items and is more efficient. Use `gateway_list_workspace` only when: 1. You need to enumerate everything independent of a task (e.g., “show me all my connections”) 2. The user has multiple connections for the same service and you need to see all of them to disambiguate (e.g., “which Gmail should I use?“) 3. `capabilities_discover` returned `alternativesAvailable` and you want to show alternatives to the user
`gateway_read_artifact`	Read a stored artifact by file_id + chatId (both returned by gateway_write_artifact / gateway_list_artifacts). Pick at most ONE extraction mode — smartGrepQuery (natural-language), search (keyword), start_line/end_line (line range), or json_path (JSON) — or omit all for a raw read with offset/limit paging. (To read a workflow run’s output files instead, use workflow_results.)
`gateway_write_artifact`	Store content you already have as a downloadable file (CSV, JSON, TXT, MD, HTML, JS, TS, PY). (To store a file from a URL instead, use gateway_write_artifact_from_url.) Returns the file `id` and the `chatId` storage container it was placed in — reuse that chatId with gateway_list_artifacts / gateway_read_artifact.
`gateway_write_artifact_from_url`	Fetch a file from a URL (server-side) and store it as a downloadable artifact. Use this when you have a link (e.g. a OneDrive/Google Drive download URL); to store content you already have, use gateway_write_artifact. Returns the file `id` and the `chatId` storage container it was placed in.
`workflow_invoke`	Invoke a workflow by its automation ID and return its results. Runs the workflow’s latest published release under your identity — you can only invoke workflows you already have access to. Use the automationId returned by capabilities_discover (call it with types: [“workflow”] to discover invocable workflows). MODES: - Default (synchronous): waits for the run and returns its result. Best for short workflows. If a run exceeds ~50s it does not block or error — it returns an operationId to poll with workflow_status, exactly as fire-and-return does. - Fire-and-return (pass async: true): returns an operationId immediately without waiting. Then poll workflow_status with that operationId (~5-10s interval) until status is COMPLETE (result included) or FAILED. Use this for long-running workflows so you are not blocked waiting on the run. RESULTS & OUTPUT FILES: - When the workflow’s API trigger(s) declare a designated output, the result includes a `designatedOutputs` array — one entry per trigger: `{triggerName, stepIndex, fileName, mimeType, size, content?}` — with `content` inlined for text under the size cap. - The result also includes an `outputFiles` array of the run’s output files: `{name, size, mimeType}`. To read one that was not inlined (binary, large, or non-designated), call workflow_results with this automationId + the returned runId + the file name.
`workflow_results`	Read a workflow run’s OUTPUT FILES by automationId + runId. You usually do NOT need this: a completed workflow_invoke / workflow_status already returns small outputs inline (`designatedOutputs`) and lists every file in `outputFiles`. Use this only to fetch a file that was not inlined — large, binary, or non-designated. `runId` is REQUIRED (pass the one workflow_invoke / workflow_status returned). Operations: “list” (enumerate files), “read” (contents — pass stepIndex to disambiguate a filename reused across steps), “getUrl” (a short-lived download URL), “search” (grep within a file).
`workflow_status`	Get the status (and, when COMPLETE, the result) of a workflow run. Pass EITHER the `operationId` returned by a fire-and-return workflow_invoke, OR a `runId` together with its `automationId`. Returns RUNNING while in progress; on COMPLETE returns the run result (summary + designatedOutputs + outputFiles listing, same shape as a synchronous workflow_invoke); on FAILED returns the error. Read any listed output file with workflow_results.

agent_invoke

Invoke an agent and get its response. MODES:

Default (synchronous): waits for the agent and returns its response. Best for short tasks. If a run exceeds ~50s it does not block or error — it returns an operationId to poll with agent_status, exactly as fire-and-return does.
Fire-and-return (pass async: true): returns an operationId immediately without waiting. Then poll agent_status with that operationId (~5-10s interval) until status is COMPLETE (result included) or FAILED. Use this for long-running agents so you are not blocked waiting.

Parameters:

Parameter	Type	Required	Default	Description
`agentId`	string	Yes	—	The id of the agent to invoke. Discover invocable agents and their ids via capabilities_discover with types: [“agent”] (or gateway_list_workspace).
`message`	string	Yes	—	The message or task to send to the agent. Be clear and specific about what you need the agent to do.
`chatId`	string	No	—	Optional chat ID to continue a previous conversation. If provided, the conversation history will be loaded. If omitted, a new conversation will be started.
`messagesInResponse`	boolean	No	—	If true, adds a `messages` array to the response containing the conversation history. Each entry carries `role`, `content`, and a `sequence` — a chat-scoped message identifier. Address a message as (chatId, sequence): sequence is NOT globally unique and repeats across chats. Sequences increase but are GAPPED, not contiguous — deleted messages and tool-call/status messages keep their numbers but are filtered out of this array, so a chat with tool calls returns e.g. 1, 2, 5, 9, and the first entry is not necessarily 1. Conversations served from the legacy history path carry no `sequence` at all. Current conversations are capped at the 250 most recent messages and longer ones are silently truncated; legacy-path conversations are returned in full. There is no pagination for messages and no separate history endpoint — this flag returns the whole array on every call, so request it only when you need the history.
`async`	boolean	No	—	Fire-and-return mode. When true, returns an operationId immediately without waiting for the agent to finish; poll agent_status with that operationId until COMPLETE. Default false (waits and returns the response).

Show inputSchema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "description": "The id of the agent to invoke. Discover invocable agents and their ids via capabilities_discover with types: [\"agent\"] (or gateway_list_workspace)."
    },
    "message": {
      "type": "string",
      "description": "The message or task to send to the agent. Be clear and specific about what you need the agent to do."
    },
    "chatId": {
      "type": "string",
      "description": "Optional chat ID to continue a previous conversation. If provided, the conversation history will be loaded. If omitted, a new conversation will be started."
    },
    "messagesInResponse": {
      "type": "boolean",
      "description": "If true, adds a `messages` array to the response containing the conversation history. Each entry carries `role`, `content`, and a `sequence` — a chat-scoped message identifier. Address a message as (chatId, sequence): sequence is NOT globally unique and repeats across chats. Sequences increase but are GAPPED, not contiguous — deleted messages and tool-call/status messages keep their numbers but are filtered out of this array, so a chat with tool calls returns e.g. 1, 2, 5, 9, and the first entry is not necessarily 1. Conversations served from the legacy history path carry no `sequence` at all. Current conversations are capped at the 250 most recent messages and longer ones are silently truncated; legacy-path conversations are returned in full. There is no pagination for messages and no separate history endpoint — this flag returns the whole array on every call, so request it only when you need the history."
    },
    "async": {
      "type": "boolean",
      "description": "Fire-and-return mode. When true, returns an operationId immediately without waiting for the agent to finish; poll agent_status with that operationId until COMPLETE. Default false (waits and returns the response)."
    }
  },
  "required": [
    "agentId",
    "message"
  ]
}

agent_status

Get the status (and, when COMPLETE, the response) of an agent run. Pass the operationId returned by a fire-and-return agent_invoke. Returns RUNNING while in progress; COMPLETE with the agent response; or FAILED with the error. Parameters:

Parameter	Type	Required	Default	Description
`operationId`	string	Yes	—	The operationId returned by agent_invoke when called with async: true.

Show inputSchema

{
  "type": "object",
  "properties": {
    "operationId": {
      "type": "string",
      "description": "The operationId returned by agent_invoke when called with async: true."
    }
  },
  "required": [
    "operationId"
  ]
}

capabilities_discover

Discover available capabilities for a task. Returns lightweight recommendations for tools, agent skills, connections, and/or resources — and, opt-in, invocable workflows and agents. Call capability_details to get full details for selected items. Use the “types” parameter to filter by capability type. GATEWAY USAGE:

To find available connections and their PCIDs: call with types: [“connection”] and a request describing the service (e.g., “gmail connections”).
To find available tools: call with types: [“tool”] and a request describing what you want to do.
To discover invocable workflows/agents (OPT-IN — off by default): call with types: [“workflow”, “agent”]. Each result carries its invoke handle (automationId / agentId); invoke them via workflow_invoke / agent_invoke.
Returns IDs inline for every recommended item (PCIDs for connections, collectionIds for resources) — you do NOT need to call gateway_list_workspace afterward to get IDs.
If the response includes alternativesAvailable (e.g., {"gmail": 2}), the user has multiple connections for that service and only one was picked. Call gateway_list_workspace to see all options when the user needs to choose.

Parameters:

Parameter	Type	Required	Default	Description
`request`	string	Yes	—	Natural language description of the task (e.g., “process vendor invoices”, “create HTML dashboard”, “send email with attachments”).
`types`	string[]	No	—	Filter results to specific capability types. If omitted, returns tools, agentSkills, connections, and resources. “workflow” (invocable workflows) and “agent” (invocable agents) are OPT-IN — returned ONLY when explicitly included here, never by default, and never in the workflow-creation context. Examples: [“connection”] for connections only, [“workflow”, “agent”] to also discover invocable workflows and agents, [“tool”, “agentSkill”] for tools and skills only.
`context`	string	No	—	Optional skill-context filter. Leave unset unless you are specifically building or editing a workflow (then pass “workflow-creation”).
`bypassCache`	boolean	No	—	Testing only — omit in normal use.
`debug`	boolean	No	—	Testing only — omit in normal use.

Show inputSchema

{
  "type": "object",
  "properties": {
    "request": {
      "type": "string",
      "description": "Natural language description of the task (e.g., \"process vendor invoices\", \"create HTML dashboard\", \"send email with attachments\")."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tool",
          "agentSkill",
          "connection",
          "resource",
          "workflow",
          "agent"
        ]
      },
      "description": "Filter results to specific capability types. If omitted, returns tools, agentSkills, connections, and resources. \"workflow\" (invocable workflows) and \"agent\" (invocable agents) are OPT-IN — returned ONLY when explicitly included here, never by default, and never in the workflow-creation context. Examples: [\"connection\"] for connections only, [\"workflow\", \"agent\"] to also discover invocable workflows and agents, [\"tool\", \"agentSkill\"] for tools and skills only."
    },
    "context": {
      "type": "string",
      "enum": [
        "workflow-creation",
        "agent-execution"
      ],
      "description": "Optional skill-context filter. Leave unset unless you are specifically building or editing a workflow (then pass \"workflow-creation\")."
    },
    "bypassCache": {
      "type": "boolean",
      "description": "Testing only — omit in normal use."
    },
    "debug": {
      "type": "boolean",
      "description": "Testing only — omit in normal use."
    }
  },
  "required": [
    "request"
  ]
}

capability_details

Get the full details of capabilities returned by capabilities_discover — pass the exact names/ids from that response. For a tool: its complete input and output JSON Schema. For a workflow: its input schema (read this before workflow_invoke). For an agent: its description and output contract (read this before agent_invoke). For a connection or resource: its metadata. Use the “types” parameter to filter which kinds you want details for. Parameters:

Parameter	Type	Required	Default	Description
`items`	string[]	Yes	—	Names/IDs of capabilities to get details for (e.g., [“google-drive”, “invoice-processing”, “html-creation”, “My Google Drive Connection”, “sales”]). Use exact tool names returned from capabilities_discover.
`types`	string[]	No	—	Filter results to specific capability types. If omitted, searches tool/agentSkill/connection/resource. For a workflow discovered via capabilities_discover use [“workflow”] (returns its input schema); for an agent use [“agent”] (returns its description + output contract).
`context`	string	No	—	Caller context, matching capabilities_discover. In “workflow-creation” (the Workflow Builder) the invoke-only “workflow”/“agent” types are excluded even if requested, mirroring the discover gate.

Show inputSchema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names/IDs of capabilities to get details for (e.g., [\"google-drive\", \"invoice-processing\", \"html-creation\", \"My Google Drive Connection\", \"sales\"]). Use exact tool names returned from capabilities_discover."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tool",
          "agentSkill",
          "connection",
          "resource",
          "workflow",
          "agent"
        ]
      },
      "description": "Filter results to specific capability types. If omitted, searches tool/agentSkill/connection/resource. For a workflow discovered via capabilities_discover use [\"workflow\"] (returns its input schema); for an agent use [\"agent\"] (returns its description + output contract)."
    },
    "context": {
      "type": "string",
      "enum": [
        "workflow-creation",
        "agent-execution"
      ],
      "description": "Caller context, matching capabilities_discover. In \"workflow-creation\" (the Workflow Builder) the invoke-only \"workflow\"/\"agent\" types are excluded even if requested, mirroring the discover gate."
    }
  },
  "required": [
    "items"
  ]
}

code-execution_execute

Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers. Available globals:

callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context.
codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns { success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use gateway_write_artifact.
codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns { success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use gateway_read_artifact after code execution returns.
console.log/error/warn(…args) — Captured to logs array returned in the response.
setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution).

EXAMPLES: // Call MCP tools (DO NOT pass PCID - connection is auto-injected from selection context): const emails = await callTool(“gmail”, “gmail_search_emails”, { query: “is:unread” }); // Create output files: const csv = emails.map(e => ${e.from},${e.subject}).join(‘\n’); await codeExec.createArtifact(‘emails.csv’, csv, ‘csv’); // Read an artifact from the conversation: const data = await codeExec.readArtifact(‘file_abc123’); console.log(data.content); // Return result to agent: return { count: emails.length }; LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read_artifact to access the full result. IMPORTANT — NO UNBOUNDED LOOPS:

NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout.
If a tool doesn’t have a pagination parameter (e.g. “page”), do NOT attempt manual pagination — you will get the same page repeatedly.
If you need more data than one API call returns, return what you have and tell the user the tool’s page limit was reached.
Bounded loops (e.g. for(let i=0; i<items.length; i++)) over local data are fine.
Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total.

Default timeout: 10 minutes (max 15 minutes). GATEWAY CONNECTION HANDLING: Connections are auto-injected for all callTool() calls inside the sandbox — do NOT put PCIDs in the code.

If the user has one connection per service, it is used automatically.
If the user has multiple connections for the same service, use the connectionSelections parameter to specify which one: {“gmail”: “<pcid>”}. Obtain PCIDs via capabilities_discover with types: [“connection”].
callTool(server, tool, args) uses the same server identifiers as gateway_invoke (from capability_details), e.g. “gmail”, “dynamic/<id>”, “remote/<id>”.
When connectionSelections is omitted, the first connection per service is used as default.

Parameters:

Parameter	Type	Required	Default	Description
`code`	string	Yes	—	JavaScript code to execute in the sandbox. The code runs in an async context — use await for async operations. Return a value to send it back to the agent. Example: const collections = await callTool(“datastore-unstructured”, “datastore-unstructured_list_collections”, {}); const csv = collections.collections.map(c => c.name).join(‘\n’); await codeExec.createArtifact(‘collections.csv’, csv, ‘csv’); return { count: collections.collections.length };
`timeout`	number	No	`600000`	Timeout in milliseconds (default: 600000 = 10 minutes, min: 1000 = 1 second, max: 900000 = 15 minutes)
`connectionSelections`	any	No	—	Optional mapping of service key to PCID for callTool() connection injection. Use this when the user has multiple connections for the same service and you need to select a specific one. Keys are service names (e.g., “gmail”, “slack”), values are PCIDs obtained from capabilities_discover. When omitted, connections are auto-selected (first connection per service). Code should NOT contain PCIDs — pass them here instead so code remains portable across users.

Show inputSchema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "JavaScript code to execute in the sandbox.\n\nThe code runs in an async context — use await for async operations.\nReturn a value to send it back to the agent.\n\nExample:\nconst collections = await callTool(\"datastore-unstructured\", \"datastore-unstructured_list_collections\", {});\nconst csv = collections.collections.map(c => c.name).join('\\n');\nawait codeExec.createArtifact('collections.csv', csv, 'csv');\nreturn { count: collections.collections.length };\n"
    },
    "timeout": {
      "type": "number",
      "default": 600000,
      "description": "Timeout in milliseconds (default: 600000 = 10 minutes, min: 1000 = 1 second, max: 900000 = 15 minutes)"
    },
    "connectionSelections": {
      "type": "effects",
      "description": "Optional mapping of service key to PCID for callTool() connection injection. Use this when the user has multiple connections for the same service and you need to select a specific one. Keys are service names (e.g., \"gmail\", \"slack\"), values are PCIDs obtained from capabilities_discover. When omitted, connections are auto-selected (first connection per service). Code should NOT contain PCIDs — pass them here instead so code remains portable across users."
    }
  },
  "required": [
    "code"
  ]
}

gateway_invoke

Invoke a single MCP tool on a registered server. Good for simple, one-shot tool calls. NOTE: Results are returned in full (not truncated). This is fine for most calls, but if a tool is likely to return a large amount of data (e.g., searching hundreds of emails, bulk exports, large query results), prefer code-execution_execute instead — it automatically saves large results as artifacts. CONNECTION HANDLING:

Connections are auto-injected. If the user has one connection for a service (e.g., one Gmail account), it is used automatically — do NOT pass PCID.
If the user has MULTIPLE connections for the same service, pass a PCID (Pinkfish Connection ID) to select which one. Discover available connections and their PCIDs via capabilities_discover with types: [“connection”].
Do NOT pass PCID in the “arguments” object — use the top-level PCID parameter instead.

For complex multi-step operations, data processing, file creation, or tool calls expected to return large results, use code-execution_execute instead. Parameters:

Parameter	Type	Required	Default	Description
`server`	string	Yes	—	Server name or path (e.g., “gmail”, “slack”, “dynamic/amplitude”, “remote/linear-official-mcp”). Use capability_details to find exact server names and tool schemas.
`tool`	string	Yes	—	The tool name to call (e.g., “gmail_search_emails”, “slack_send_message”). Use capability_details to find exact tool names and their required arguments.
`arguments`	object	No	`{}`	Tool arguments as key-value pairs. Do NOT include PCID here — use the top-level PCID parameter instead.

Show inputSchema

{
  "type": "object",
  "properties": {
    "server": {
      "type": "string",
      "description": "Server name or path (e.g., \"gmail\", \"slack\", \"dynamic/amplitude\", \"remote/linear-official-mcp\"). Use capability_details to find exact server names and tool schemas."
    },
    "tool": {
      "type": "string",
      "description": "The tool name to call (e.g., \"gmail_search_emails\", \"slack_send_message\"). Use capability_details to find exact tool names and their required arguments."
    },
    "arguments": {
      "type": "object",
      "additionalProperties": true,
      "default": {},
      "description": "Tool arguments as key-value pairs. Do NOT include PCID here — use the top-level PCID parameter instead."
    },
    "PCID": {
      "type": "string",
      "description": "Pinkfish Connection ID — selects which connection to use when the user has multiple connections for the same service. Leave empty for auto-selection (works when the user has exactly one connection per service). Obtain PCIDs via capabilities_discover with types: [\"connection\"]."
    }
  },
  "required": [
    "server",
    "tool"
  ]
}

gateway_list_artifacts

List the files in a storage container. Returns each file’s name, id, size, MIME type and creation date — use this to find a file’s id before gateway_read_artifact. Parameters:

Parameter	Type	Required	Default	Description
`chatId`	string	Yes	—	Storage container to list (from a gateway_write_artifact response)
`filter_type`	string	No	—	Filter by MIME type prefix (e.g., “text/”, “application/json”)
`filter_name`	string	No	—	Filter by filename pattern (case-insensitive substring match)

Show inputSchema

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "description": "Storage container to list (from a gateway_write_artifact response)"
    },
    "filter_type": {
      "type": "string",
      "description": "Filter by MIME type prefix (e.g., \"text/\", \"application/json\")"
    },
    "filter_name": {
      "type": "string",
      "description": "Filter by filename pattern (case-insensitive substring match)"
    }
  },
  "required": [
    "chatId"
  ]
}

gateway_list_workspace

List everything in the user’s workspace: connections, resources (datastores, filestores, knowledge bases, vaults), and invocable workflows + agents. Returns every item with its ID (PCID for connections, collectionId for resources, automationId for workflows, agentId for agents) and name. Prefer capabilities_discover for task-relevant work — that tool returns IDs inline for recommended items and is more efficient. Use gateway_list_workspace only when:

You need to enumerate everything independent of a task (e.g., “show me all my connections”)
The user has multiple connections for the same service and you need to see all of them to disambiguate (e.g., “which Gmail should I use?”)
capabilities_discover returned alternativesAvailable and you want to show alternatives to the user

Parameters: None

Show inputSchema

{
  "type": "object",
  "properties": {}
}

gateway_read_artifact

Read a stored artifact by file_id + chatId (both returned by gateway_write_artifact / gateway_list_artifacts). Pick at most ONE extraction mode — smartGrepQuery (natural-language), search (keyword), start_line/end_line (line range), or json_path (JSON) — or omit all for a raw read with offset/limit paging. (To read a workflow run’s output files instead, use workflow_results.) Parameters:

Parameter	Type	Required	Default	Description
`file_id`	string	Yes	—	The file ID of the artifact to read
`chatId`	string	Yes	—	Storage container the artifact is in. From a gateway_write_artifact response or gateway_list_artifacts.
`offset`	number	No	—	Character offset to start from. Use nextOffset from a previous response to continue reading.
`limit`	number	No	—	Max characters per call. Default: 10K (raw) or 100K (smartGrepQuery).
`smartGrepQuery`	string	No	—	Natural language query for LLM-powered extraction (e.g., “list all names and emails as a table”)
`search`	string	No	—	Search pattern to find in the content (case-insensitive). Returns matching lines with context.
`context_lines`	number	No	—	Number of context lines around each search match (default: 2)
`start_line`	number	No	—	Start line number for line range extraction (1-indexed)
`end_line`	number	No	—	End line number for line range extraction (1-indexed)
`json_path`	string	No	—	Dot notation path to extract from JSON (e.g., “data.items”, “results[0]“)
`array_indices`	string	No	—	Comma-separated indices or ranges (e.g., “0,1,2” or “0-5”)

Show inputSchema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "description": "The file ID of the artifact to read"
    },
    "chatId": {
      "type": "string",
      "description": "Storage container the artifact is in. From a gateway_write_artifact response or gateway_list_artifacts."
    },
    "offset": {
      "type": "number",
      "description": "Character offset to start from. Use nextOffset from a previous response to continue reading."
    },
    "limit": {
      "type": "number",
      "description": "Max characters per call. Default: 10K (raw) or 100K (smartGrepQuery)."
    },
    "smartGrepQuery": {
      "type": "string",
      "description": "Natural language query for LLM-powered extraction (e.g., \"list all names and emails as a table\")"
    },
    "search": {
      "type": "string",
      "description": "Search pattern to find in the content (case-insensitive). Returns matching lines with context."
    },
    "context_lines": {
      "type": "number",
      "description": "Number of context lines around each search match (default: 2)"
    },
    "start_line": {
      "type": "number",
      "description": "Start line number for line range extraction (1-indexed)"
    },
    "end_line": {
      "type": "number",
      "description": "End line number for line range extraction (1-indexed)"
    },
    "json_path": {
      "type": "string",
      "description": "Dot notation path to extract from JSON (e.g., \"data.items\", \"results[0]\")"
    },
    "array_indices": {
      "type": "string",
      "description": "Comma-separated indices or ranges (e.g., \"0,1,2\" or \"0-5\")"
    }
  },
  "required": [
    "file_id",
    "chatId"
  ]
}

gateway_write_artifact

Store content you already have as a downloadable file (CSV, JSON, TXT, MD, HTML, JS, TS, PY). (To store a file from a URL instead, use gateway_write_artifact_from_url.) Returns the file id and the chatId storage container it was placed in — reuse that chatId with gateway_list_artifacts / gateway_read_artifact. Parameters:

Parameter	Type	Required	Default	Description
`filename`	string	Yes	—	Name of the file with extension (e.g. “data.csv”)
`content`	string	Yes	—	The file content as a string
`fileType`	string	Yes	—	File extension/type
`chatId`	string	No	—	Storage container to place the file in (from a previous gateway_write_artifact response). Omit to create a new container.
`agentId`	string	No	—	Advanced; leave unset (used only when auto-creating a container).

Show inputSchema

{
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
      "description": "Name of the file with extension (e.g. \"data.csv\")"
    },
    "content": {
      "type": "string",
      "description": "The file content as a string"
    },
    "fileType": {
      "type": "string",
      "enum": [
        "csv",
        "json",
        "txt",
        "md",
        "html",
        "js",
        "ts",
        "py"
      ],
      "description": "File extension/type"
    },
    "chatId": {
      "type": "string",
      "description": "Storage container to place the file in (from a previous gateway_write_artifact response). Omit to create a new container."
    },
    "agentId": {
      "type": "string",
      "description": "Advanced; leave unset (used only when auto-creating a container)."
    }
  },
  "required": [
    "filename",
    "content",
    "fileType"
  ]
}

gateway_write_artifact_from_url

Fetch a file from a URL (server-side) and store it as a downloadable artifact. Use this when you have a link (e.g. a OneDrive/Google Drive download URL); to store content you already have, use gateway_write_artifact. Returns the file id and the chatId storage container it was placed in. Parameters:

Parameter	Type	Required	Default	Description
`sourceUrl`	string	Yes	—	The URL to fetch the file content from (e.g., a download URL from OneDrive or Google Drive)
`filename`	string	Yes	—	Name for the artifact file with extension (e.g. “report.pdf”, “data.xlsx”)
`authHeaders`	object	No	—	Optional request headers for the fetch, as a JSON map — e.g. {“Authorization”: “Bearer <token>”}.
`chatId`	string	No	—	Storage container to place the file in (from a previous gateway_write_artifact response). Omit to create a new container.
`agentId`	string	No	—	Advanced; leave unset (used only when auto-creating a container).

Show inputSchema

{
  "type": "object",
  "properties": {
    "sourceUrl": {
      "type": "string",
      "description": "The URL to fetch the file content from (e.g., a download URL from OneDrive or Google Drive)"
    },
    "filename": {
      "type": "string",
      "description": "Name for the artifact file with extension (e.g. \"report.pdf\", \"data.xlsx\")"
    },
    "authHeaders": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional request headers for the fetch, as a JSON map — e.g. {\"Authorization\": \"Bearer <token>\"}."
    },
    "chatId": {
      "type": "string",
      "description": "Storage container to place the file in (from a previous gateway_write_artifact response). Omit to create a new container."
    },
    "agentId": {
      "type": "string",
      "description": "Advanced; leave unset (used only when auto-creating a container)."
    }
  },
  "required": [
    "sourceUrl",
    "filename"
  ]
}

workflow_invoke

Invoke a workflow by its automation ID and return its results. Runs the workflow’s latest published release under your identity — you can only invoke workflows you already have access to. Use the automationId returned by capabilities_discover (call it with types: [“workflow”] to discover invocable workflows). MODES:

Default (synchronous): waits for the run and returns its result. Best for short workflows. If a run exceeds ~50s it does not block or error — it returns an operationId to poll with workflow_status, exactly as fire-and-return does.
Fire-and-return (pass async: true): returns an operationId immediately without waiting. Then poll workflow_status with that operationId (~5-10s interval) until status is COMPLETE (result included) or FAILED. Use this for long-running workflows so you are not blocked waiting on the run.

RESULTS & OUTPUT FILES:

When the workflow’s API trigger(s) declare a designated output, the result includes a designatedOutputs array — one entry per trigger: {triggerName, stepIndex, fileName, mimeType, size, content?} — with content inlined for text under the size cap.
The result also includes an outputFiles array of the run’s output files: {name, size, mimeType}. To read one that was not inlined (binary, large, or non-designated), call workflow_results with this automationId + the returned runId + the file name.

Parameters:

Parameter	Type	Required	Default	Description
`automationId`	string	Yes	—	Automation ID of the workflow to invoke (from capabilities_discover).
`inputs`	object	No	—	Input values for the workflow as key-value pairs, matching the workflow’s input schema (see capability_details). Ephemeral — does not modify the workflow.
`maxWaitMs`	number	No	—	[Testing only] Maximum internal polling time in milliseconds before returning RUNNING. Default 14 minutes.
`async`	boolean	No	—	Fire-and-return mode. When true, returns an operationId immediately without waiting for the run to finish; poll workflow_status with that operationId until COMPLETE. Default false (waits and returns the result).

Show inputSchema

{
  "type": "object",
  "properties": {
    "automationId": {
      "type": "string",
      "description": "Automation ID of the workflow to invoke (from capabilities_discover)."
    },
    "inputs": {
      "type": "object",
      "additionalProperties": true,
      "description": "Input values for the workflow as key-value pairs, matching the workflow's input schema (see capability_details). Ephemeral — does not modify the workflow."
    },
    "maxWaitMs": {
      "type": "number",
      "description": "[Testing only] Maximum internal polling time in milliseconds before returning RUNNING. Default 14 minutes."
    },
    "async": {
      "type": "boolean",
      "description": "Fire-and-return mode. When true, returns an operationId immediately without waiting for the run to finish; poll workflow_status with that operationId until COMPLETE. Default false (waits and returns the result)."
    }
  },
  "required": [
    "automationId"
  ]
}

workflow_results

Read a workflow run’s OUTPUT FILES by automationId + runId. You usually do NOT need this: a completed workflow_invoke / workflow_status already returns small outputs inline (designatedOutputs) and lists every file in outputFiles. Use this only to fetch a file that was not inlined — large, binary, or non-designated. runId is REQUIRED (pass the one workflow_invoke / workflow_status returned). Operations: “list” (enumerate files), “read” (contents — pass stepIndex to disambiguate a filename reused across steps), “getUrl” (a short-lived download URL), “search” (grep within a file). Parameters:

Parameter	Type	Required	Default	Description
`automationId`	string	Yes	—	Automation ID
`runId`	string	Yes	—	REQUIRED on the gateway. Pass the runId returned by workflow_invoke / workflow_status.
`operation`	string	Yes	—	Operation type: “list” (get artifact summaries with structure/preview/tips — best first step after workflow_run, especially to spot HTML/UI outputs), “search” (regex search across files), “read” (read actual data), “getUrl” (get signed URL for a file)
`pattern`	string	No	—	[search] Regex pattern to search for across all output files. Case-insensitive.
`limit`	number	No	`10`	[search] Maximum number of matches to return. Default: 10.
`filename`	string	No	—	[read/getUrl] Name of the output file to read or get URL for. Examples: “data.json”, “stdout.txt” (full execution logs — JSON with log field), “dashboard.html” (fetch the rendered HTML artifact directly).
`stepIndex`	number	No	—	[read/getUrl] The step that produced the file. Filenames are per-step keys and can repeat across steps, so pass this to disambiguate (e.g. when a designatedOutput tip names a stepIndex). Omit to match the first file with that name.
`path`	string	No	—	[read] Path to extract specific data. Supports dot notation (data.users.0.name) and bracket notation (data.users[0].name). Examples: “tickets.0” (first ticket), “data.users[1]” (second user), “users[0].email”. Does not support wildcards or negative indices.
`sample`	number	No	—	[read] Return only first N items from array. Useful for inspecting structure without loading all data.
`offset`	number	No	—	[read] Pagination offset - skip first N items. Combine with limitRead for pagination.
`limitRead`	number	No	—	[read] Pagination limit - return N items after offset.
`fields`	string[]	No	—	[read] Field projection - return only specified fields from objects. Example: [“id”, “subject”] returns only those fields.

Show inputSchema

{
  "type": "object",
  "properties": {
    "automationId": {
      "type": "string",
      "description": "Automation ID"
    },
    "runId": {
      "type": "string",
      "description": "REQUIRED on the gateway. Pass the runId returned by workflow_invoke / workflow_status."
    },
    "operation": {
      "type": "string",
      "enum": [
        "list",
        "search",
        "read",
        "getUrl"
      ],
      "description": "Operation type: \"list\" (get artifact summaries with structure/preview/tips — best first step after workflow_run, especially to spot HTML/UI outputs), \"search\" (regex search across files), \"read\" (read actual data), \"getUrl\" (get signed URL for a file)"
    },
    "pattern": {
      "type": "string",
      "description": "[search] Regex pattern to search for across all output files. Case-insensitive."
    },
    "limit": {
      "type": "number",
      "default": 10,
      "description": "[search] Maximum number of matches to return. Default: 10."
    },
    "filename": {
      "type": "string",
      "description": "[read/getUrl] Name of the output file to read or get URL for. Examples: \"data.json\", \"stdout.txt\" (full execution logs — JSON with log field), \"dashboard.html\" (fetch the rendered HTML artifact directly)."
    },
    "stepIndex": {
      "type": "number",
      "description": "[read/getUrl] The step that produced the file. Filenames are per-step keys and can repeat across steps, so pass this to disambiguate (e.g. when a designatedOutput tip names a stepIndex). Omit to match the first file with that name."
    },
    "path": {
      "type": "string",
      "description": "[read] Path to extract specific data. Supports dot notation (data.users.0.name) and bracket notation (data.users[0].name). Examples: \"tickets.0\" (first ticket), \"data.users[1]\" (second user), \"users[0].email\". Does not support wildcards or negative indices."
    },
    "sample": {
      "type": "number",
      "description": "[read] Return only first N items from array. Useful for inspecting structure without loading all data."
    },
    "offset": {
      "type": "number",
      "description": "[read] Pagination offset - skip first N items. Combine with limitRead for pagination."
    },
    "limitRead": {
      "type": "number",
      "description": "[read] Pagination limit - return N items after offset."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "[read] Field projection - return only specified fields from objects. Example: [\"id\", \"subject\"] returns only those fields."
    }
  },
  "required": [
    "automationId",
    "runId",
    "operation"
  ]
}

workflow_status

Get the status (and, when COMPLETE, the result) of a workflow run. Pass EITHER the operationId returned by a fire-and-return workflow_invoke, OR a runId together with its automationId. Returns RUNNING while in progress; on COMPLETE returns the run result (summary + designatedOutputs + outputFiles listing, same shape as a synchronous workflow_invoke); on FAILED returns the error. Read any listed output file with workflow_results. Parameters:

Parameter	Type	Required	Default	Description
`operationId`	string	No	—	The operationId returned by a fire-and-return workflow_invoke (async: true).
`runId`	string	No	—	A run id to poll instead of operationId — requires automationId.
`automationId`	string	No	—	The run’s automationId — required when polling by runId.

Show inputSchema

{
  "type": "object",
  "properties": {
    "operationId": {
      "type": "string",
      "description": "The operationId returned by a fire-and-return workflow_invoke (async: true)."
    },
    "runId": {
      "type": "string",
      "description": "A run id to poll instead of operationId — requires automationId."
    },
    "automationId": {
      "type": "string",
      "description": "The run's automationId — required when polling by runId."
    }
  }
}

Platform API

Embedded MCP Servers

Application MCP Servers

Triggers API

Tools

agent_invoke

agent_status

capabilities_discover

capability_details

code-execution_execute

gateway_invoke

gateway_list_artifacts

gateway_list_workspace

gateway_read_artifact

gateway_write_artifact

gateway_write_artifact_from_url

workflow_invoke

workflow_results

workflow_status

​Tools

​agent_invoke

​agent_status

​capabilities_discover

​capability_details

​code-execution_execute

​gateway_invoke

​gateway_list_artifacts

​gateway_list_workspace

​gateway_read_artifact

​gateway_write_artifact

​gateway_write_artifact_from_url

​workflow_invoke

​workflow_results

​workflow_status

Tools

agent_invoke

agent_status

capabilities_discover

capability_details

code-execution_execute

gateway_invoke

gateway_list_artifacts

gateway_list_workspace

gateway_read_artifact

gateway_write_artifact

gateway_write_artifact_from_url

workflow_invoke

workflow_results

workflow_status