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, tag fields take names rather than IDs, prefer bulk tools over loops. It is kept deliberately short because clients truncate it — Claude Code cuts it at 2KB — so it works as a routing note rather than a manual.
Model documentation resources
Everything the guide is too small to hold is served as MCP resources under ceum://model/. Clients that support resources can read them on demand; in Claude Code they also appear in the @ autocomplete as @ceum:ceum://model/….
| Resource | Covers |
|---|---|
ceum://model/index |
Index of the docs below. The server instructions point here. |
ceum://model/classification |
Status vs task type vs tag — which of the three a given label belongs in, and where flagged and priority sit. |
ceum://model/task-structure |
Breaking work down: the subtask rules (one level of nesting, and the task type must allow the position) and when a link or relationship fits better. |
ceum://model/relationships |
Typed directional relationships (blocks, relates to) versus untyped many-to-many links. |
ceum://model/identifiers |
Display IDs versus UUIDs, and which argument takes which. |
ceum://model/conventions |
Read-before-write, bulk over loops, the two kinds of error, pagination, scope, auditing. |
ceum://model/crm |
Clients and projects: many-to-many rather than a hierarchy, what drives follow-up alerts, and what each delete leaves behind. |
ceum://model/time-tracking |
Running vs finished entries, what auto-stop does to the previous session, and how aggregation windows and groups work. |
ceum://model/finance |
Invoices, transactions and subscriptions — how little they connect, how totals and the tax split behave, and what a renewal creates. |
ceum://model/calendar |
How recurring events are stored and edited, the mutation scopes, the all-day encoding, and the merged calendar view. |
ceum://model/documents |
When a version snapshot is taken, and why restoring moves history forward rather than back. |
ceum://model/configuration |
Managing the catalogs, per-project scoping, custom fields, kanban boards, and settings. |
ceum://model/search |
What search_workspace covers, and the two things it silently leaves out. |
These describe the data model itself, not your workspace. They contain no personal data and are readable by any valid token, including one granted no tools.
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/resume, 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.