# MCP Tools Reference | Albato Embedded Docs

Source: https://albato.com/wiki/articles/mcp-tools-reference

Welcome to Albato Help

Search articles

# MCP Tools Reference

Last update:  
2/9/2026 · 17 min read

* * *

IN THIS ARTICLE

This is the reference for all nine tools your AI agent can call through Albato's MCP server: what each tool does, its parameters, its response shape, and the design rationale behind it.

The design rationale for each tool is included on purpose. It explains why your agent calls tools in a specific order, why some parameters are required and others aren't, and what to check first if a call doesn't behave the way you expect.

| Setting | Value |
| --- | --- |
| Endpoint | **<MCP\_SERVER\_URL>/mcp** |
| Authentication | **Authorization: Bearer <virtual\_key>**, a virtual key of the form **mcp\_vk\_...** (recommended). For backward compatibility, a direct Albato token is also accepted. See the [Virtual Keys guide](https://albato.com/wiki/articles/mcp-managing-virtual-keys). |

## 1\. find\_action

Finds an app (partner), its matching actions, and the user's existing connections. Always called first. **Always takes an array** of **queries**, one call for the entire scenario.

i

**What the agent sees.** Find apps, their actions, and available connections. Before calling, identify all apps and actions the entire scenario requires: pass them all in a single call. Do not call **find\_action** multiple times for different steps of the same scenario.

For operations that create a new object (note, task, call, email) that must be linked to another object (deal, contact, company), include a dedicated association action in your upfront plan (for example, actionQuery: "associate note"). Always pass a **queries** array, one item per app/action needed. Use this before **get\_action\_schema** and **run\_action\_sync**.

If multiple partners match **serviceQuery**, status is "multiple\_partners": call again with a more specific **serviceQuery**. If connections is empty or any action has connected: false, use **create\_connection\_link** with the **partnerId** to get a setup URL for the user. If connections has multiple items, ask the user which one to use.

Each item in the response includes a "status" field: "success", "not\_found", "multiple\_partners", or "error".

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| queries | array | **Yes** | Array of **{ serviceQuery, actionQuery }** objects. Pass all needed apps/actions in one call, executed in parallel. |

Fields of an object in **queries**:

| Field | Type | Description |
| --- | --- | --- |
| serviceQuery | string | App name, e.g. **"HubSpot"** |
| actionQuery | string | Action name, e.g. **"find deal"** |

**Response**

Always an array, one item per request:

`[   {   "index": 0,   "status": "success",   "partnerId": 10001,   "partnerTitle": "HubSpot",   "actions": [   {   "triggerActionId": 20001,   "title": "Find deal",   "description": "...",   "hasCredentialWizard": false   }   ],   "connections": [   {   "credentialId": 90001,   "title": "My HubSpot account",   "isDefault": false,   "createdAt": "2026-06-23 21:29:47"   }   ]   },   {   "index": 1,   "status": "not_found",   "query": { "serviceQuery": "Unknown", "actionQuery": "..." }   }   ]`

Item statuses: **success**, **not\_found**, **multiple\_partners**, **error**. On **multiple\_partners**, call again with a more specific serviceQuery.

**Native adapter partners** (for example HubSpot, when native routing is enabled for the contract) return a different shape:

-   each item in **actions** includes **connected:** , whether the user has at least one connection to the adapter
-   **connections** is a list of **{ connectionId, displayName, adapterId, source: "native" }** instead of **credentialId**
-   if there are no connections, **actions** is empty and the response includes a **\_hint** pointing to **create\_connection\_link**

**Design rationale**

One request (partner + actions + connections) instead of three separate ones reduces LLM inferences. Each inference costs about 3 to 8 seconds.

Always an array: a single interface without switching between single and bulk modes. The agent always knows the response format, and one request covers the whole scenario instead of N sequential calls.

**hasCredentialWizard** in the response flags that this action needs **get\_credential\_wizard\_step** instead of a plain **credentialId**. This is needed for apps with extra connection parameters, for example Google Sheets: account, then spreadsheet, then sheet.

## 2\. get\_action\_schema

Returns the input field schema for actions. Must be called before **run\_action\_sync**. **Always takes an array** of **actions**.

i

**What the agent sees.** Get action input schemas. Always pass an "actions" array, one item per action.

For native adapter actions (**triggerActionId** starts with "native:"), **credentialData** is not required: the hub resolves the token automatically. For standard Albato actions, **credentialData** is required: use {"0": {"value": <credentialId>}} where **credentialId** comes from **find\_action** connections; for wizard actions pass the full **currentCredentialData** from the completed wizard.

With **fieldFilter**: returns matching fields plus required fields, sufficient for **run\_action\_sync**. Without **fieldFilter**: returns required fields only. If no required fields exist, returns empty **variables** with a \_hint: always follow up with **fieldFilter**.

Each item in the response includes a "status" field: "success" or "error".

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| actions | array | **Yes** | Array of objects, all requests run in parallel |

Fields of an object in **actions**:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| partnerId | number | **Yes** |  |
| triggerActionId | number | **Yes** |  |
| credentialData | object | **Yes\*** | Standard connection: **{"0": {"value": }}**.   Wizard action: the final currentCredentialData from the completed wizard (complete=true).   \*Not needed for native adapter actions (**triggerActionId** starts with "native:"), the token is resolved automatically |
| fieldFilter | string\[\] | **No** | Individual words to match fields by name/label, e.g. **\["note", "body", "text"\]**, not phrases. Without the filter, required fields only |
| useCache | boolean | **No** | Default: true. Schemas are cached for 10 minutes |
| cacheTtl | number | **No** | Cache TTL in seconds, max 86400 |

**Response**

Always an array:

`[   {   "index": 0,   "status": "success",   "variables": [   { "name": "query", "label": "Search query", "type": "string", "isRequired": true, "isReadOnly": false },   { "name": "hs_note_body", "label": "Text", "type": "string", "isRequired": false, "isReadOnly": false }   ],   "rowSections": [...]   }   ]`

Statuses: **success**, **error**. If there are no fields and fieldFilter was not passed, **variables** is empty, and the response includes a **\_hint** suggesting to add fieldFilter.

**Design rationale**

**credentialData** is a single parameter for both connection types of Albato actions. Standard action: **{"0": {"value": credentialId}}**. Wizard action: the full accumulated **currentCredentialData**. There is no separate **credentialId** parameter, this simplifies the interface. For native adapter actions the parameter is not needed: the hub resolves the user's OAuth token automatically.

The schema is not returned in full by default: some actions have 50 to 200 fields. Without fieldFilter, required fields only. With fieldFilter, required fields plus keyword matches.

**fieldFilter uses individual words, not phrases**: substring search over name and label. The field **hs\_note\_body** (label "Text") won't be found by "note body" (space is not underscore), but will be found by "text". If a field isn't found after one attempt, don't retry with other words: the action simply doesn't support it.

## 3\. run\_action\_sync

Executes an action synchronously and returns the result.

i

**What the agent sees.** Run action synchronously. Always call **get\_action\_schema** before this tool: never guess field names. Use the "name" field from each variable as the key in **runnerData**.

For native adapter actions (**triggerActionId** starts with "native:"), **credentialData** is not required: the hub resolves the token automatically. If the user has multiple connections for this adapter, pass "**connectionId**" from **find\_action** connections list; if only one connection exists it is selected automatically.

For standard Albato actions, **credentialData** is required: use {"0": {"value": <credentialId>}}; for wizard actions pass the full **currentCredentialData** from the completed wizard.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| partnerId | number | **Yes** |  |
| triggerActionId | number | **Yes** |  |
| connectionId | string | **No** | Only for native adapter actions with multiple connected accounts: **connectionId** from the connections list in the **find\_action** response.   If there's only one connection, it's selected automatically and this can be omitted |
| credentialData | object | **Yes\*** | Standard connection: **{"0": {"value": }}**.   Wizard action: the final currentCredentialData from the completed wizard.   \*Not needed for native adapter actions: the call will fail without it for other actions |
| runnerData | object | **Yes** | Data to execute with, fields from the **get\_action\_schema** schema |
| useCache | boolean | **No** | Default: false. Can be enabled for read-only actions (get deal, get contact) |
| cacheTtl | number | **No** | Default: 60 seconds |

**Response**

`{   "success": true,   "albatoResponse": {   "success": true,   "data": {   "eventData": [{   "data": {   "variables": [   { "n": "Deal ID", "v": "500000000001" },   { "n": "Deal Name", "v": "Cool deal" }   ]   }   }]   }   }   }`

**Design rationale**

**Always synchronous**: Albato also supports an async mode, but it's inconvenient for agents, it requires polling for status, which adds inferences. Synchronous mode is simpler and faster for the agent, even though it keeps the HTTP connection open for the duration of execution.

**get\_action\_schema is required before this call**: this is explicitly stated in the tool description. Without the schema, the agent guesses field names, gets a validation error, and has to retry, adding two extra inferences.

**credentialData is unified for Albato actions**: one parameter for both standard and wizard actions. Native adapter actions don't require it; instead, **connectionId** is passed when there are multiple accounts.

**useCache for read-only calls**: the agent often requests the same data multiple times within a session (for example deal data at different stages). Caching avoids repeated API calls to Albato.

## 4\. get\_credential\_wizard\_step

Used for actions with **hasCredentialWizard=true**. Iteratively collects connection settings through a multi-step dialog.

i

**What the agent sees.** Use when action has hasCredentialWizard=true. Iteratively collects multi-step connection settings, for example account, then spreadsheet, then sheet.

1.  If **credentialId** is already known from **find\_action**, start immediately with {"0":{"value":<credentialId>}}, skip the empty first call. Otherwise call with {} to get step 0 options.
2.  Show options to user, get their choice.
3.  Call again with **currentCredentialData** built from chosen values: {"0":{"value":<chosen>}, ...}.
4.  Repeat until complete=true.
5.  Pass the final **currentCredentialData** as **credentialData** to **get\_action\_schema** and **run\_action\_sync**.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| triggerActionId | number | **Yes** |  |
| currentCredentialData | object | **No** | Values accumulated so far: **{"0":{"value":90002},"1":{"value":"40002"}}**. Omit or pass **{}** for the first call |

**Response**

`{   "complete": false,   "steps": [   { "index": 0, "label": "Select account", "values": null },   {   "index": 1, "label": "Select spreadsheet",   "values": { "40001": "Test sheet for automation", "40002": "MCP demo spreadsheet" }   }   ]   }`

Once all steps are filled, **complete: true**. The final **currentCredentialData** is passed as **credentialData** to **get\_action\_schema** and **run\_action\_sync**.

**Design rationale**

Some apps require more than just an OAuth connection: they also require selecting a specific object inside the account, for example which sheet in Google Sheets, which base in Airtable, which page in Notion. These parameters can't be hardcoded into the schema: they depend on the user's data.

**An iterative approach**, step by step, is used rather than one big form, because each step may depend on the previous one. The list of Google Sheets tabs can't be retrieved until a spreadsheet is chosen.

**If credentialId is already known** (it came from **find\_action**), the first step can be skipped by passing it right away. This saves one call.

## 5\. create\_connection\_link

Creates a link for the user to connect their account to an app, using the same underlying connection mechanism described in [Connecting Apps in Albato](https://albato.com/wiki/articles/key-access-creation).

!

**Important.** Requires connection-management to be enabled for your contract. Contact your Albato manager if this returns a **404**.

i

**What the agent sees.** Create a connection link for the user to authorize an app.

For native adapter partners (for example HubSpot), returns an oauthUrl and **adapterId**: open the URL in a browser, then call **check\_connection\_status** with {"adapterId": "<adapterId>"}. Each call creates a new connection (account): call again to add more accounts for the same app.

For standard Albato partners, returns **sharingId** and linkUrl: share with the user, then call **check\_connection\_status** with {"sharingId": <sharingId>}.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| partnerId | number | **Yes** |  |
| title | string | **No** | Connection label shown to the user (Albato mode only) |

**Response**

Native adapter partner (for example HubSpot, PKCE OAuth):

`{   "mode": "native_oauth",   "adapterId": "hubspot-native",   "oauthUrl": "[https://app.hubspot.com/oauth/authorize](https://app.hubspot.com/oauth/authorize)?...",   "humanActionRequired": true,   "nextStep": "open_oauth_url_in_browser_then_call_check_connection_status",   "checkWith": "check_connection_status with {"adapterId": "hubspot-native"}"   }`

Standard Albato partner:

`{   "sharingId": 30001,   "linkUrl": "[https://albato.com/connect/](https://albato.com/connect/)...",   "mode": "albato",   "status": "waiting",   "humanActionRequired": true,   "nextStep": "share_link_with_user_and_wait_confirmation"   }`

**Design rationale**

The user never hands their OAuth credentials to the agent directly: that would be unsafe. For Albato partners, the agent gets a one-time link, the user goes through Albato's standard OAuth flow, and the server receives a **credentialId** once it's done.

For native adapter partners, the hub manages the OAuth flow directly with the provider (HubSpot, etc.) using a secure PKCE flow: the agent never sees the user's tokens. The OAuth link expires after 10 minutes if not completed; call **create\_connection\_link** again to get a fresh one.

Each call for a native adapter creates a **new** connection (account): calling it again lets you add a second account for the same app without replacing the first.

## 6\. check\_connection\_status

Checks connection status. Native adapter by **adapterId**; Albato by **sharingId**.

i

**What the agent sees.** Check connection status.

For native adapter connections, pass {"adapterId": "<adapterId>"} (returned by **create\_connection\_link**). This returns a "connections" list with **connectionId** and displayName for each authorized account. For Albato connections, pass {"sharingId": <sharingId>}.

Ask the user to complete the connection first, then call once to verify. Do not poll automatically.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| adapterId | string | **No\*** | Native adapter flow, from the **create\_connection\_link** response |
| sharingId | number | **No\*** | Albato flow, from the **create\_connection\_link** response |

\*Exactly one of the two is passed, depending on which flow **create\_connection\_link** returned.

**Response**

Native adapter flow:

`{   "adapterId": "hubspot-native",   "connected": true,   "connections": [   { "connectionId": "a1b2c3...", "displayName": "My Team" }   ],   "humanActionRequired": false,   "nextStep": "continue_with_action"   }`

Albato flow:

`{ "status": "ready", "credentialId": 90001, "humanActionRequired": false, "nextStep": "continue_with_action" }`

Albato flow statuses: **waiting**, **ready**, **oauth\_pending**, **revoked**.

**Design rationale**

The agent calls it once, after the user confirms: it does not poll automatically. This is intentional:

1.  Automatic polling means extra inferences while the user is going through OAuth.
2.  Race condition: if the agent checks before the connection is finalized, it gets pending/waiting and may run into an auth error.
3.  The user knows best when they clicked "Allow": their confirmation ("done") is the signal.

## 7\. disconnect\_adapter

Removes one or all native adapter connections (revokes access).

!

**Important.** Native adapter and connection-management tools must be enabled for your contract. Contact your Albato manager if this returns a **404**.

i

**What the agent sees.** Remove a native adapter connection (revoke access).

Pass **adapterId** and optionally **connectionId** to remove a specific account. Omit **connectionId** to remove all accounts for this adapter.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| adapterId | string | **Yes** | E.g. **"hubspot-native"** |
| connectionId | string | **No** | A specific account to remove. Without it, all connections for this adapter for the user are removed |

**Response**

`{ "disconnected": true, "adapterId": "hubspot-native", "connectionId": "a1b2c3..." }`

Without **connectionId**: **{ "disconnected": true, "adapterId": "hubspot-native", "deletedCount": 2 }**.

**Design rationale**

Applies only to native adapter connections, which require authenticating with a virtual key (mcp\_vk\_...). For Albato connections (regular credentials), see **disconnect\_partner** below.

The explicit "one account" and "all accounts" split avoids accidentally removing extra connections when the user has several accounts for the same app.

## 8\. disconnect\_partner

Removes a single Albato connection (credential) to a partner. Does not touch native adapter connections: use **disconnect\_adapter** for those.

!

**Important.** Connection-management tools must be enabled for your contract. Contact your Albato manager if this returns a **404**.

i

**What the agent sees.** Remove an Albato connection (credential) to a partner app. Requires **partnerId** and **credentialId**, both come from **find\_action** or **list\_connections** connections list.

This deletes a single credential. It does not affect native adapter connections; use **disconnect\_adapter** for those.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| partnerId | number | **Yes** | From **find\_action** |
| credentialId | number | **Yes** | From the connections list in the **find\_action**/**list\_connections** response (the **albatoConnections** field) |

**Response**

`{ "disconnected": true, "partnerId": 10001, "credentialId": 90001 }`

Error for a nonexistent/already-removed **credentialId**:

`{   "error": {   "type": "partner_error",   "message": "Albato API request failed.",   "details": { "status": 400, "data": { "success": false, "errors": ["Invalid credential ID"] } }   }   }`

**Design rationale**

Only accepts a single **credentialId** per call: there's no "remove all connections for this partner" mode. To remove multiple credentials, call the tool once per **credentialId**.

## 9\. list\_connections

Returns **all** of the current user's connections in a single call, with no arguments. Covers both native adapter accounts and standard Albato credentials, across every app at once.

i

**What the agent sees.** List all of the current user's connections across every app, no arguments needed.

Returns **nativeConnections** (native adapter accounts authorized via OAuth, e.g. HubSpot) and **albatoConnections** (standard Albato credentials).

Use this to show the user what they already have connected, or to find a **connectionId**/**credentialId** without calling **find\_action** first.

**Parameters**

None. The tool takes no arguments.

**Response**

`{   "nativeConnections": [   {   "adapterId": "hubspot-native",   "adapterTitle": "HubSpot",   "connectionId": "a1b2c3...",   "displayName": "My Team",   "expiresAt": "2026-08-21 19:40:00",   "createdAt": "2026-07-01 10:00:00"   }   ],   "albatoConnections": [   {   "credentialId": 90001,   "partnerId": 10001,   "partnerTitle": "HubSpot",   "title": "My HubSpot account",   "isDefault": false,   "environment": "albato",   "source": "albato",   "createdAt": "2026-06-23 21:29:47"   }   ]   }`

**nativeConnections** is empty if native adapter connections aren't enabled for your contract, or if you're authenticating with a direct Albato token instead of a virtual key. The tool doesn't fail, it just omits that part.

**Design rationale**

**find\_action** already returns connections, but only for one specific partner. To find out everything that's connected, the agent would have to guess and iterate over apps. **list\_connections** gives the full picture in one call.

**partnerTitle in albatoConnections**: raw credentials from Albato only include **partnerId**, with no human-readable app name. The hub fills in **partnerTitle** for each entry; without this, neither the agent nor the user could tell which app a connection belongs to.

The tool is always present in tools/list, unlike **create\_connection\_link**, **check\_connection\_status**, or **disconnect\_adapter**: the Albato part works regardless of whether native adapter connections are enabled for your contract.

See the [MCP Usage Scenarios](https://albato.com/wiki/articles/mcp-usage-scenarios) guide for end-to-end call sequences using these tools, and [MCP Architectural Principles](https://albato.com/wiki/articles/mcp-architectural-principles) for the design reasoning behind them.

Need help? Contact your Albato manager or reach out to the Albato technical team.

## Related articles

-   [MCP Usage Scenarios](https://albato.com/en/wiki/articles/mcp-usage-scenarios)

Did this answer your question?