MCP tools

The connector has 40 tools: 12 reads and 28 writes. Every feature has a tool that reads it, a save_ tool that creates or changes it, and a delete_ tool that removes it. It also has 2 prompts, draft_rules and check_a_change.

• A read tool returns data and never changes anything.
• A write tool changes data in your account. It needs a connection with Read and change access. See Access levels.
• A destructive write can overwrite or remove data: a record, a holding, a rule or a list member. It changes only what the call names. Every write is destructive except record_cash_movement and send_feedback, which only add. Allocait marks these tools as destructive. What your app does with that mark is up to the app.
• A connection from an account whose agent access is read-only can’t change data, even if you chose Read and change. A write returns “This account’s agent access is read-only.” See Access and limit errors.

The REST API has the same features, plus webhooks and display preferences, which stay in the app and REST. See the API overview.

​

Tools by area

​

All tools at a glance

​

How saves work

Every save_ tool follows the same rules:

• Create or change. Leave out the id to create. Pass the id to change that record.
• Fields. A field you send replaces the stored value. A field you leave out keeps its value. null clears a field that can be cleared and counts as left out on any other.
• Lists. A list you send is the whole list, in that order. If it would drop members that are stored now, the call is refused with CONFIRMATION_REQUIRED and names them. To keep them, add them to the list you send. To drop them, ask the user, then send the call again with those members in remove. On save_playbook, save_monitor and save_chart, remove alone, with no list, drops those members, and the result’s removed says what went.
• Names. Creating a record with a name that’s already taken returns ALREADY_EXISTS with the existing id instead of a second record with that name.
• Reads match saves. A read returns each record with the same field names its save tool takes, so an agent can read, edit and save without renaming anything.
• Unknown fields. A save refuses a field the tool doesn’t take, in the call or in one of its rows, and saves nothing. The error names the field and the likely match, such as Unknown field(s): descripton (did you mean description?), so a misspelled field name is refused instead of silently dropped.
• Misspelled fields on a read. A read tool ignores a field it has no use for, since an app may add its own. It refuses one that looks like a misspelling of a field it takes, such as price for prices or from for since, and names the likely match, so a field that looks like a misspelling of one the tool takes is refused instead of silently ignored.
• Results. A save returns the keys its output schema lists, such as the ids it created or changed and which positions were created, updated, unchanged or closed.

Deletes take the id. Deleting something that’s already gone returns NOT_FOUND.

​

Next steps