MCP Tools Reference

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.

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.

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.

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.

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.

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.

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?...",
"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/...",
"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.

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).

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.

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.

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 guide for end-to-end call sequences using these tools, and 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