Route each operation#
Choose ClickUp and GitHub backends independently. Hosted ClickUp uses official
OAuth MCP; direct GitHub actions use the selected backend (gh by default or an
explicitly selected approved hosted GitHub connection). Reuse account sign-in
across authorized repositories and verify each project target; no per-repository
token is required for gh. Strict remote-only permits hosted connections
only and forbids gh. Missing or banned selected tools mean STOP, not fallback.
Never use cup, cu-work or a bridge for hosted ClickUp. Follow the
host guard protocol
before hosted writes; these are agent checks outside helper receipts/locks/gates.
Local ClickUp helper commands below apply only in explicit local-helper mode.
Read the binding and inventory only tools actually present in this session. The backends are cup, rest-mcp (Joel Thornton), context-mcp (hauptsacheNet), official (ClickUp), github-cli, and github-mcp.
| Need | First candidate | Reason |
|---|---|---|
| Exact task, subtask, status, comment, custom field, dependency | cup |
Small JSON commands and file-based text input |
| Task plus comments/images/context | context-mcp |
May consolidate several reads; discover the exposed mode |
| Broad REST API operation without cup | rest-mcp |
Free local MCP with individual operation tools |
| Broad workspace search / official-specific functionality | official |
Official search and service coverage; inspect limits |
| Branch, PR, checks, issue | gh or GitHub MCP |
Use the available tool with complete fields and least extra work |
Authentication-aware routing: The table above describes a full local-helper
installation with a working cup token. In the default OAuth host-agent
installation, use the connected official ClickUp MCP for ClickUp operations
and the selected GitHub backend (gh by default, or approved hosted tools); never choose cup,
rest-mcp, or unbound clickup_work merely because it appears in a client
tool list. Those are separate authentication and receipt domains. Before
any host write, load the guarded OAuth issue-first protocol.
The local helper's route_operation only advises and may lack a project
binding in host-mode sessions. No automatic fallback to the CLI after a
host write failure.
Run, for example:
cu-work --project-dir /absolute/worktree route task.context --available cup,context-mcp,official
Or call route_operation with the absolute project_dir, operation, and available backend names. A route is advice, not execution or an availability probe. Per-project overrides can reorder it. These defaults are not measured latency/token benchmarks.
For MCP, inspect the selected tool's current input schema and returned fields. Names in the route output are hints, not guarantees. A read-minimal context MCP cannot write just because its full version has create tools. Do not register all servers to perform one task. Prefer native IDs, filtered/paginated reads, and compact responses; retrieve comments/images only when needed. A limited search returning no match does not prove absence. For cup tasks or cup search, use --all for team-wide work and scope to the bound list.
Use a complete-read backend for reconciliation: the pinned cup comments and
REST MCP list_comments expose one page, so the helper stops at 25 comments.
For longer local histories, explicitly select routing.comment_reader=clickup-api
with private environment credentials for GET-only cursor reads; writes remain
on the selected upstream runtime and there is no automatic fallback. Use
paginated host MCP reads for threaded replies. Link
GitHub before any subtask creation regardless of the selected backend; routing
a create call directly does not exempt it from clickup-github's association rules.
The cu-work executable and its own MCP can directly execute scoped writes through cup or the configured rest-mcp runtime. Host context-mcp, official ClickUp MCP, and GitHub MCP are invoked by the agent, not proxied by this helper. When using host tools directly, perform fresh workspace/list/ancestry checks and preserve operation markers/receipts yourself. The helper's journal does not capture host calls.
If the selected backend is unavailable, stop and report it. A user may explicitly
choose another allowed backend before a new operation, after its authentication
and scope are verified. This is not automatic fallback. After a timeout, malformed
response, rate-limit error during a write, or other uncertain outcome, inspect
remote state first; never replay through another backend. Use cu-work reconcile
only for local-helper receipts after establishing what applied. Stop when
authorization, scope or required evidence cannot be established.
Keep tokens in each teammate's account. Free MCP software still uses services with API/plan limits. Do not install paid/proprietary servers or claim one backend is faster without evidence.