# 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:

```json
{
  "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`.

```json
{
  "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](/docs/embedded/embedded-mcp/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.