Tools Reference
The Chainabit cloud MCP server surfaces 41 tools through tools/list. Every one of them acts on your Chainabit account — never on the NEXUS desktop app running on your machine. If both MCP servers are connected, read NEXUS local MCP vs Chainabit cloud MCP before choosing a tool.
How scoping works
Every call is bound to the identity carried by your OAuth access token. You cannot address another account's data by passing an identifier, and identifiers are validated against your membership rather than trusted from the model:
- Account — the Chainabit account the token was issued for.
- Workspace — the workspace that account is currently working in. Workspace-scoped tools read and write only inside it.
get_workspace_infoaccepts an explicitworkspaceId, but resolves it against your own membership. - User — tasks, goals, memories, and calendar entries belong to the signed-in user within that workspace.
Entitlements gate the tools:
| Entitlement | Covers |
|---|---|
mcp.tools.read | Every tool below except the ones noted otherwise. Read and write task, goal, memory, and sandbox tools all consume this budget. |
mcp.tools.write | update_agent only. |
nexus.room | nexus_room_join, nexus_room_say, nexus_room_history, trigger_agent, trigger_team. |
nexus.desktop | get_nexus_entitlements. |
See Plans & Rate Limits for how those map onto plans and rate buckets.
Writes over MCP execute immediately
Several tools ask for approval when they run inside a Chainabit AI conversation, where the product renders an approval card. An MCP request has no such surface, so a write tool called over MCP takes effect when it is called. Treat every tool that creates or changes data as immediate, and confirm with the person you are helping first.
The one exception is bits_delete, which enforces a two-step protocol in the tool contract itself — see below.
Orientation
Call these first to find out what you are connected to.
get_bot_info
Returns the server's name, description, and a summary of the capability families it offers. Takes no arguments. The cheapest way to confirm you are talking to the Chainabit cloud server.
get_workspace_context
Returns the caller's account identifier, current workspace identifier, and the MCP scopes granted by their plan. Takes no arguments. Useful as a first call, so later calls do not need extra round-trips to discover the active workspace.
get_workspace_info
Fetches metadata for a workspace — name, plan, member count, and configuration.
Args: workspaceId (optional; defaults to the active workspace). An explicit id is resolved against your own membership, so naming a workspace you do not belong to returns nothing.
get_nexus_entitlements
Returns the account's NEXUS Desktop feature entitlements: which features are enabled and any hard limits on sessions, agents, and workspaces. Takes no arguments. Call once after connecting and cache the result.
This reports what the account is entitled to. It does not inspect, and cannot inspect, a NEXUS app running on your machine.
Requires nexus.desktop.
Tasks — bits_*
A bit is a single actionable task. For a goal, project, or multi-step initiative, use chainies_* instead.
bits_query
The most versatile task search. Combines date range, status, priority, goal, chain, parent, overdue flag, and text search, with cursor pagination.
Args: dateFrom, dateTo (YYYY-MM-DD), status (pending | completed | skipped | failed | archived), priority (low | medium | high | critical), chainyId, chainId, parentId (a task id, or the literal root for top-level tasks only), overdue, query, limit (1–50, default 20), cursor.
Pagination is sequential: pass the nextCursor from the previous response verbatim. Cursor values are opaque and only ever come from a prior response.
bits_get
Fetches a single task by id, including the full note body that list responses truncate.
Args: bitId (required).
bits_search
Keyword search over task titles and notes, with optional status, priority, goal, and date-range filters. Use bits_query when there is no text query, or when you need pagination.
Args: query (required), limit (1–50, default 20), chainyId, status, priority, dateFrom, dateTo.
bits_create
Creates one or more tasks. For a single task pass title plus optional fields; for several, pass an items array rather than calling repeatedly. scheduledDate defaults to today and priority defaults to medium. Supply chainyId or chainId to file the task under a goal or a chain.
bits_update
Updates one or more tasks. For a single task pass bitId plus only the fields to change; for several, pass an items array. Setting status to completed marks a task done and accepts an optional completionNote. chainyId moves the task to a different goal; chainId re-assigns it to a different chain.
bits_move
Re-files a task under a different goal or chain. Prefer bits_update for general edits; this tool exists for explicit re-assignment.
Args: bitId (required), plus at least one of chainyId or chainId.
bits_reprioritize
Applies priority changes to many tasks in one operation, intended as the follow-up to a priority analysis. Each entry carries a task id, a new priority, and an optional short rationale.
Args: chainyId (required), updates (required; 1–100 entries of bitId + priority, optional rationale), reason (optional summary).
bits_delete
Deletes a bounded batch of tasks by id. This tool requires two calls. Call it first with previewOnly: true to obtain the exact list of affected tasks and a previewToken; show that list to the user; then call again with previewOnly: false and the token you were given. The token binds the deletion to the set that was previewed, so nothing can be removed that the user did not see.
Args: bitIds (required), previewOnly (required), previewToken (required when previewOnly is false).
Each deleted task disappears from every view immediately and is removed from AI memory, then is permanently purged after a 30-day recovery window. The purge cannot be reversed through the tools.
Calendar — calendar_*
Calendar tools read and reschedule the same tasks the bits_* family manages; they differ only in how they select them. Their results are never served from cache, so a query made at a day boundary always reflects the current date.
calendar_today
Returns the tasks scheduled for today, ordered by priority. For any other date — a specific day, tomorrow, next week — use bits_query with dateFrom and dateTo.
Args: chainyId (optional).
calendar_week
Returns the tasks scheduled for a given week. weekOffset is 0 for this week, 1 for next, -1 for last; the server computes the Monday–Sunday range, so the client does not have to.
Args: weekOffset, chainyId, status, limit (1–50, default 30), cursor.
calendar_range
Returns the tasks scheduled inside an arbitrary date range, up to 90 days.
Args: from and to (both required, YYYY-MM-DD), chainyId, limit (1–50, default 20), cursor.
calendar_overdue
Returns pending tasks whose scheduled date has already passed.
Args: limit (1–50, default 20), cursor.
calendar_unscheduled
Returns pending tasks with no scheduled date — the backlog of unplanned work.
Args: chainyId, limit, cursor.
calendar_reschedule
Moves a task to a different date, and optionally a different time.
Args: bitId and scheduledDate (both required), scheduledTime (optional).
Board view
kanban_board
Returns a board view of tasks grouped into status columns — pending, completed, skipped, failed — optionally scoped to a goal or a chain. One call gives a snapshot of every stage of work at once.
Args: chainyId, chainId, limitPerColumn.
Goals — chainies_*
A chainy is a goal, project, app, or multi-step initiative. It groups related chains and tasks under one intent.
chainies_get
Fetches one goal in full detail by chainyId, or lists goals when no id is given.
Args: chainyId (omit to list), status, limit (1–50, default 20), cursor. Listing paginates sequentially — pass nextCursor verbatim as the next cursor.
chainies_search
Finds goals by keyword, matching titles and descriptions.
Args: query (required), limit (1–50, default 20).
chainies_create
Creates a goal. Only title is required.
Args: title (required), description, category, targetDate, colorHex.
Prefer this over bits_create whenever the request describes a project, app, goal, or initiative rather than a single task. For several projects, create one goal each.
Chains
A chain is a repeatable workflow or scheduled execution with streak tracking. Chains are not goals — goals are chainies_*.
list_chains
Lists the user's chains in the active workspace.
Args: limit (default 20, max 100), offset (default 0).
get_chain
Fetches one chain by id, including streak counts, schedule, and the goal it belongs to.
Args: id (required).
Agents
These act on cloud agent records in your Chainabit account. A local NEXUS roster agent is a different thing entirely, and agent_create exists on both servers — see NEXUS local MCP vs Chainabit cloud MCP.
list_agents
Lists the AI agent instances configured in the account, with id, display name, model, and persona.
Args: limit (default 20, max 100), offset (default 0).
get_agent
Fetches one agent's full configuration by id — name, model, persona, system prompt, and tool entitlements.
Args: id (required).
search_agents
Finds agents whose name contains a substring, case-insensitive. Use when the person refers to an agent by partial name rather than by id.
Args: q (required), limit, offset.
agent_create
Creates a new persistent cloud agent in the workspace, with its own persona, base model, and memory mode. The agent is usable immediately.
Args: name, persona, and base_model (all required), plus optional configuration.
update_agent
Changes an existing agent's display name, persona, or preferred model. At least one of those must be supplied.
Args: agentId (required), name, persona, base_model.
Requires mcp.tools.write — the only tool that does.
Memory — memory_*
This is the cloud memory store attached to your Chainabit account. It is a separate store from NEXUS's local memory: an entry written in one is not retrievable from the other.
memory_search
Searches stored memories — durable facts, preferences, goals, and context.
Args: query, type, chainyId, limit.
memory_store
Stores a new memory.
Args: content (required), type, chainyId, importance, tags.
Reserve this for durable preferences, instructions, and facts that will matter in later conversations. Single-session context, task-specific detail, and answers to one-off questions do not belong here.
Models
models_search
Lists the AI models available to the account, filterable by provider or capability, with each model's capabilities, tool support, and context-window size. Never returns pricing or internal identifiers.
Args: provider, capability, activeOnly (defaults to true).
Connectors — connectors_*
connectors_list
Lists the integrations connected in the active workspace, with their status. active means connected and enabled; passive means disabled, errored, or awaiting authentication.
Args: q, status.
connectors_get
Fetches one connected integration in detail — status, health, and the tools it exposes. Identify it by instanceId (from connectors_list) or by name.
Args: instanceId or name.
Note: these two tools describe connectors. The cloud MCP server does not currently expose a tool for invoking a connector's own actions.
Cloud sandbox — workspace_*
A persistent cloud sandbox attached to the workspace. It is a remote environment, not your local machine, and it has no access to your filesystem.
workspace_run
Runs a shell command in the sandbox and returns its exit code and output. The command runs under a strict timeout and its output streams back as it runs.
Args: command (required), cwd, timeoutMs.
workspace_files
Reads or writes a file inside the sandbox. Paths are relative to the workspace root; large files are truncated on read.
Args: op and path (both required), plus the content to write.
Room — nexus_room_*, trigger_*
These are cloud tools
nexus_room_join,nexus_room_say, andnexus_room_historyare served here, by the Chainabit cloud MCP server. They carry the NEXUS name, but they do not touch the local NEXUS 2D Room, its agents, or anything visible in the NEXUS app window. If the person means the Room they can see on screen, none of these tools is the right one — see NEXUS local MCP vs Chainabit cloud MCP.
The Room here is a shared cloud space attached to a workspace, where cloud agents and connected clients show presence and talk to one another. Every tool in this section needs an active workspace and requires nexus.room.
nexus_room_join
Joins the workspace's room as a live character so other participants can see you. Call once before nexus_room_say or trigger_agent. Returns the room id.
This is a cloud tool. It does not join the local NEXUS Room.
Args: actorLabel (required — your display handle, e.g. @my-client), roomId (omit for the workspace's default room), actorType (cli_worker | platform_agent, defaults to cli_worker), activityState (optional initial activity).
nexus_room_say
Posts a durable utterance, or broadcasts an ephemeral activity state. Does not spend AI credits.
This is a cloud tool. Nothing it posts appears in the local NEXUS Room.
Args: actorLabel (required), content (required for kind: utterance, max 4000 characters), kind (utterance | activity, defaults to utterance), activityState (when kind is activity), roomId, inReplyTo.
nexus_room_history
Fetches recent room messages, newest first. Page backwards by passing the returned nextCursor as before.
This is a cloud tool. It returns cloud room history, not local NEXUS Room history.
Args: roomId, limit (1–100, default 30), before (ISO timestamp cursor).
trigger_agent
Wakes a cloud agent to do work and reply in the room. Returns the trigger and reply message ids and the run id.
Spends AI credits from your wallet. Bounded by trigger depth and rate limits.
Args: targetAgentId and prompt (both required, prompt max 8000 characters), roomId, actorLabel, inReplyTo.
trigger_team
Wakes every member of a team to do work and reply in the room. Returns each member's trigger and reply message ids and run id, or that member's error — one member failing does not stop the others.
Spends AI credits from your wallet, per member. Bounded by trigger depth and rate limits, the same as trigger_agent.
Args: teamId and prompt (both required, prompt max 8000 characters), roomId, actorLabel, inReplyTo.
Wired but not surfaced
These exist in the server but are disabled, and do not appear in tools/list. Calling one by name returns an unknown-tool error. They may be enabled in a later release:
search_chains— substring search over chain nameslist_workspaces— every workspace the caller belongs tolist_workspace_members— the members of a workspaceget_usage_summary— a current-period usage snapshotplanning_generate,planning_list,planning_get,planning_decompose— the planning family
Earlier revisions of this page documented list_connector_instances and execute_connector_tool. Neither is served. Use connectors_list and connectors_get to inspect connectors.