Embedded MCP tool calls

Learn the eight Embedded MCP tools, their access levels, JSON inputs, results, and tool error format.

Embedded MCP has eight tools. The server registers each tool according to the API key's access level. Every call runs for the end user in the URL.

Choose a tool

Minimum key access	Tools
Read Only	`search-apps`, `search-actions`, `get-action-schema`, `list-connections`, `query-result-set`
Run Workflows	All Read Only tools, plus `execute-actions` and `resolve-lookup`
Full Access	All tools, plus `get-connect-url`

Search the published app catalog first. Use the returned slug as appRef, then search its actions. If search returns one suggestedAction with a schema, use that schema. Otherwise call get-action-schema. Resolve lookup-backed arguments before execution.

When several accounts connect to the same app, list-connections returns their IDs. Pass the chosen connectionId as connectionRef to execute-actions or resolve-lookup.

Call and result format

MCP tools/call sends the tool name and its JSON arguments. For example:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search-apps","arguments":{"q":"slack"}}}

Each successful tool returns one text item containing JSON. Parse that item's text to read data and any meta.

{"success":true,"data":{"items":[{"id":"app_slack","slug":"slack","name":"Slack"}],"limit":20,"nextCursor":null}}

A failed tool sets isError: true. Its text normally contains { "success": false, "error": { "code", "message", "nextStep", "retryable" } }. Input schema errors and unknown tool names can return plain text instead. Read errors and limits before adding retries.

Tool page examples show illustrative IDs and app actions. Read the live schema before sending an action's arguments.