This page explains the cross-cutting behavior every MCP tool shares. Per-tool detail lives in the category articles linked from MCP Tools Reference.
Connection model
Ceum's MCP server speaks Streamable HTTP. Clients authenticate with a workspace-scoped token created from Integrations and MCP; the token's prefix is shown in the audit log so you can trace which client made a call. Tokens carry the scope of the user who created them, so revoking one stops every client using it.
On initialize, the server returns a short usage guide (the "server instructions") that points clients at the most common pitfalls: list statuses before creating entities, "Bug" is a task type not a status, prefer flag_task over editing flags on update, prefer start_time_session over generic create-style calls for the timer. The full guide is built into the server and surfaced verbatim to compatible clients.
Reads vs. mutations
Every tool is tagged as either non-mutating (a read) or mutating. Mutating tools cover create, update, delete, bulk-update, bulk-delete, pause/unpause, start/stop, restore, and similar verbs. Non-mutating tools cover list, get, search, and aggregate.
The distinction matters because:
- Mutations are audited. Every mutating call is recorded in the MCP audit log with the tool name, the token that made the call, the affected item, the input it was given, and a timestamp. The history is kept indefinitely, and revoking a token does not erase it. You can review it from Integrations and MCP.
- Reads are not. Read calls would otherwise dwarf the audit volume. They still run with the access of the token's owner.
- Side effects compound. Deleting a project also deletes its dependent items; restoring a document version archives the current content first; pausing a subscription stops its renewals immediately. Each per-tool article spells out these effects explicitly.
IDs at the boundary
Most entity tools accept either a full UUID or a display ID (T-7, P-3, C-12, D-9). The boundary handler resolves display IDs to UUIDs before the service layer ever sees them, so an agent that already has a display ID from a previous response can pass it directly without an extra lookup.
The same applies to relationship-target fields: targetId, projectId, taskId, and clientId arguments accept both forms.
Status conventions
Task, project, and client statuses are user-configurable. The defaults follow Backlog → Todo → Planning → In Progress → Review → Done for tasks, and an analogous pipeline for projects, but the user can rename or reorder them. Always call list_task_statuses, list_project_statuses, or list_client_statuses before creating or updating entities so you use a valid statusId. The tools accept the statusId slug returned by those calls.
A status flagged finished: true is treated as a "done" state — entities in that status are hidden by default in list queries. A status flagged backlog: true is treated as inactive (typically excluded from active boards). Both flags are exposed in task and project list_*_statuses output; client statuses are a flat lifecycle and do not support these flags.
Pagination and limits
List tools accept page (1-indexed) and limit. The server clamps limit to a maximum (currently 50 for most entities, 200 for documents) and defaults to 20 when omitted. Sort fields and direction (sortBy, sortOrder) are enumerated per-tool in the parameter tables.
Bulk operations
Where a category supports bulk (bulk_create_*, bulk_update_*, bulk_delete_*), prefer the bulk tool over looping single-entity calls. Bulk tools transact internally and the audit log records each entity separately so the trace remains per-entity.
Errors
Tools reject invalid input — missing required fields, unknown enum values, unknown entity IDs, or references that don't resolve — with an error that names the failing field. Agents should surface the error verbatim rather than retrying with guessed inputs.