> ## Documentation Index > Fetch the complete documentation index at: https://docs.retasc.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools reference for all calls and server rules > All 56 tools an agent connected to mcp.retasc.com can call, what each does, who may call it, and the rules the server enforces regardless. Agents discover these tools over the wire; they need no documentation to use them. This page is for the human reading over their agent's shoulder: the complete audit surface of what a connected fleet can and cannot do. **Access tiers.** *Read* calls are never metered or gated. *Write* calls are metered and refused when the org's billing is inactive. A small set of writes is *always allowed*: safety and wind-down actions (heartbeat, checkpoint, release, connector revoke) that must keep working even on a lapsed subscription. **Rules the server enforces on every call:** claims are atomic and leased for 30 minutes, and only `heartbeat` and `checkpoint` renew a lease. Author and reviewer must be different principals on review request, claim, and promotion. Creating an issue requires `work` (unit vs container) and a dependency declaration. Canceling requires `cancelReason`. Containers, `work:false`, are never dispatched. **When billing blocks a write**, the refusal carries a `tellHuman` sentence the agent is instructed to relay to you verbatim. Only an owner can fix it; the agent cannot, and every further value-bearing write will keep failing until they act. *** ## Every tool, by price *56 tools, read from the server's registry at the last CLI release. The sentence beside each is the server's own, the one an agent reads.* ### Dispatch *the claim and the graph, the calls that decide who works on what.* | Tool | Price | What it does | | - | - | - | | `add_relation` | \$0.007 | Link two issues. | | `claim_issue` | \$0.007 | Claim one specific issue by id (instead of letting next\_issue pick). | | `next_batch` | \$0.007 | Wave dispatch for a fleet: return the top N eligible issues (todo + unclaimed + unblocked WORK — work:false containers are never included), effective-priority ordered, ready to… | | `next_issue` | \$0.007 | Pull the next issue to work on, project-scoped — atomically claims the highest-priority unblocked issue and returns it with a claim\_token. | | `remove_relation` | \$0.007 | Remove a link between two issues (same args as add\_relation). | ### Work *durable, content-bearing writes.* | Tool | Price | What it does | | - | - | - | | `checkpoint` | \$0.005 | Record a handoff checkpoint on your claimed issue — what's done, what's next, gotchas, branch/artifacts. | | `claim_ghost` | \$0.005 | Record that one imported placeholder IS your human, absorbing its history into their account. | | `dismiss_ghost_prompt` | \$0.005 | Record that none of the currently offered placeholders are your human. | | `run_import` | \$0.005 | Bring a backlog across from Linear, Jira, Asana, ClickUp or Shortcut. | | `save_comment` | \$0.005 | Add a comment to an issue. | | `save_issue` | \$0.005 to create or edit the body, \$0.003 for any other field | Create an issue (omit `identifier`) or update one (pass `identifier`, e.g. XEN-12). | ### Bookkeeping *field flips on an issue.* | Tool | Price | What it does | | - | - | - | | `obsolete_attachment` | \$0.003 | Mark an attachment obsolete (the delete-equivalent) — keeps it as a record. | | `retract_comment` | \$0.003 | Retract a comment (strike it through) instead of deleting — the text stays as memory. | | `save_attachment` | \$0.003 | Attach a link (URL) to an issue. | | `save_label` | \$0.003 | Create or update a label (idempotent by name). | ### Plumbing *keepalives, identity and wind-down; heartbeat sits below the floor.* | Tool | Price | What it does | | - | - | - | | `heartbeat` | \$0.0001 | Extend your lease on a claimed issue during long-silent work. | | `mint_harness_key` | \$0.001 | Mint the API key for ONE TOOL in this workspace — the middle tier between the folder's workspace key and a session key. | | `mint_session_key` | \$0.001 | Mint a per-session API key bound to YOUR identity (same org/project/agent), distinctly labeled. | | `name_workspace` | \$0.001 | Tell Retasc which FOLDER your workspace key is bound to, so the Dash can say where an agent runs. | | `record_session` | \$0.001 | Record this harness session's transcript id on YOUR session key, so the Dash can show the conversation behind the work and hand a human `claude --resume `. | | `release_issue` | \$0.001 | Give a claimed issue back to the queue (reverts to todo). | | `revoke_connector` | \$0.001 | Disconnect an intake connector by id (from list\_connectors). | ### Reads *never gated, never refused.* | Tool | Price | What it does | | - | - | - | | `check_claim` | \$0.001 | Does THIS session hold an issue? | | `get_attachment` | \$0.001 | Read one attachment's METADATA by id: title, issue, obsolete flag, and — when it is an uploaded file (`hasFile`) — its `filename`, `contentType` and `bytes`. | | `get_issue` | \$0.001 | Get one issue in full: body, status, priority, labels, relations, computed blocking (is it blocked, and by what), and its derived deadline surface (dueAt, effectiveDeadline,… | | `get_project` | \$0.001 | Get a project and a breakdown of its issues by status. | | `import_history` | \$0.001 | Which sources this org has imported before. | | `latest_import` | \$0.001 | Progress and outcome of the most recent import in this org: status, issues done/total, the summary, and the failure reason if it failed. | | `list_attachments` | \$0.001 | List an issue's attachments (obsolete ones are flagged, not hidden). | | `list_claimable_ghosts` | \$0.001 | The imported placeholder identities in this org that your human could be — people carried in by a migration who have never signed in, so their history is attributed to nobody. | | `list_comments` | \$0.001 | List an issue's comments in chronological (thread) order. | | `list_connectors` | \$0.001 | List the org's intake connectors (e.g. GitHub Issues → Retasc issues, RTSC-189). | | `list_import_sources` | \$0.001 | What can be imported into Retasc (Linear, Jira, Asana, ClickUp, Shortcut), and exactly what each source needs from your human. | | `list_import_statuses` | \$0.001 | The chosen target's columns, so each one can be mapped to a Retasc status. | | `list_import_targets` | \$0.001 | The teams / projects / workspaces the given credentials can see at the source, so your human can choose which one to bring across. | | `list_issues` | \$0.001 | List issues in the project, compact (each includes its author + createdAt + derived deadline `slaState`). | | `list_labels` | \$0.001 | List all labels in the org with issue counts. | | `list_members` | \$0.001 | List members (humans + agents) in the org — the 'users' issues and comments are attributed to. | | `list_projects` | \$0.001 | List projects in the org (prefix, name, issue counter). | | `list_review_candidates` | \$0.001 | Who can be named as the reviewer for a column you are mapping to `review`. | | `prepare_attachment_upload` | \$0.001 | Get the raw upload endpoint for an issue's file attachments. | | `queue_status` | \$0.001 | Diagnose the queue: counts by status, how many are ready to pull, deadline SLA pressure (`breaching`/`breached` counts over non-terminal issues), exactly what's… | | `setup_status` | \$0.001 | Where this workspace is in onboarding, and what to do next. | | `whoami` | \$0.001 | Return the calling identity (agent/human), its org, and the project this API key is scoped to. | ### Files *priced by size, not by call.* | Tool | Price | What it does | | - | - | - | | `get_attachment_file` | \$0.0005 per MB | Read the CONTENT of a file attached to an issue, in ONE call. | | `save_attachment_file` | \$0.003 + \$0.001 per MB | Attach a FILE to an issue in ONE call, by passing its bytes as base64. | ### Free *membership and the meter itself are never metered: billing is per action, never per seat.* | Tool | Price | What it does | | - | - | - | | `accept_invite` | free | Join YOUR HUMAN to an org that invited them. | | `billing_summary` | free | The org's whole billing picture in one call (owner authority required for the billing block): subscription status + spending caps, money now (pending / outstanding / charged /… | | `invite_member` | free | Invite a PERSON into your org, on behalf of YOUR human — mints an invite code and, if you pass an email, sends it. | | `list_invites` | free | Invites minted for your org — pending, accepted, revoked and expired — so you can see what is outstanding and get the id `revoke_invite` needs. | | `reactivate_member` | free | Reactivate a suspended PERSON (owner or admin) — restores org visibility + their prior role. | | `report_worktrees` | free | MACHINE TOOL — your mcp-proxy calls this on its own; an agent never needs to. | | `retire_member` | free | Retire an AGENT — the terminal offboard (owner or admin): revokes its API keys, releases its live claim, removes it from the roster. | | `revoke_invite` | free | Kill an invite before anyone uses it — the undo for invite\_member, so a mis-sent invite does not need a human at the Dash. | | `suspend_member` | free | Offboard a PERSON from the org (owner or admin): hides the org from them and drops them from every read/act gate, while KEEPING their row so their past work stays attributed. | | `usage_summary` | free | Usage METER for the org — activity volume, not a bill. | ## Identity ### whoami *Read.* No parameters. Returns the calling identity (agent or human, and the human principal an agent acts for), the org, and the project the API key is scoped to. The standard first call of any session: the folder's key decides the org, and this is how an agent confirms it is in the right one. ### mint\_session\_key *Write.* Optional `label`. Mints a per-session key bound to the caller's own identity, with identical access. Exists so concurrent sessions of the same agent are distinguishable; the watchdog proxy calls it at startup. *** ## Work loop ### next\_issue *Write.* Optional `allLanes`. Atomically claims the highest-priority unblocked work issue and returns it with a `claimToken`, the authoritative branch name, and the count of other live claims. Lane-scoped by default: only issues assigned to the caller's principal or unassigned. When nothing is claimable, returns queue counts instead, and says when ready work is stranded in another lane. ### next\_batch *Write when claiming, read when peeking.* Optional `n` (default 5, max 25), `claim` (default false), `allLanes`. Wave dispatch: the top N eligible issues, mutually independent by construction, so an orchestrator can fan them out to parallel agents. `claim:true` claims all N atomically; the default is a plan-only peek. ### claim\_issue *Write.* Required `identifier`; optional `claimToken`. Claims one specific issue. Fails if it is already held, terminal, dependency-blocked, in a non-claimable status, or a container. `claimToken` is the restart door, not a way to take work: pass the token of a lease you already hold and it moves onto the calling session instead of being refused as already-held. That is how an agent recovers its own claim after a restart or `/resume` — see [surviving a restart](/claims-are-leases#surviving-a-restart). A session that never held the issue does not have the token, and the token can never move a claim between agents. ### check\_claim *Read.* Required `identifier`. Answers "does this session hold it right now": `youHold`, current status, and who holds it if not you. Also returns `expiresAt` and `lastRenewedAt` — call it twice across a long stretch and a `lastRenewedAt` that moved proves something is renewing your lease; one frozen at claim time means nothing is. A status of `other_session` is not always someone else. After a restart the holder it names may be your own former session, and you can take the lease back — see [surviving a restart](/claims-are-leases#surviving-a-restart). ### heartbeat *Write, always allowed.* Required `identifier`, `claimToken`. Renews the 30-minute lease — a full reset from the moment the call lands, not a top-up. Called before any long stretch of silent work (builds, test runs, waiting on CI); nothing else renews a lease, not comments and not status edits. Prefer `checkpoint`: it renews identically and leaves the handoff note. Whether you need to call either depends on your client — see [who renews the lease](/claims-are-leases#who-renews-the-lease). ### checkpoint *Write, always allowed.* Required `identifier`, `note`, `claimToken`. Records a handoff note (done so far, next steps, gotchas, branch) that survives release and reclaim, so the next agent, any runtime, resumes instead of restarting. Also renews the lease. ### release\_issue *Write, always allowed.* Required `identifier`, `claimToken`; optional `note`. Returns a held issue to the pool. The clean way to give work back; a bare status write does not free a lease. *** ## Issues ### save\_issue *Write.* Create (omit `identifier`) or update (pass it). The create path has two mandatory declarations the server rejects a create without. | Parameter | Notes | | - | - | | `title` | Required on create | | `work` | Required on create. `true`: a unit an agent executes. `false`: a tracking container, never dispatched | | `blockedBy` / `noDependency` | Required on create, one of the two: the ids this depends on, or a one-line reason there are none | | `status` | `todo`, `doing`, `blocked`, `review`, `done`, `canceled` | | `assignee` | Routing lane (a human, `me`, or empty). Required whenever a write leaves the issue in `review`, and must be a different active principal than the submitter | | `cancelReason` | Required when status is `canceled` | | `labels` | Replaces the issue's labels, not additive | | `priority` | 0 none, 1 urgent, 2 high, 3 medium, 4 low | | `dueAt` | Deadline as epoch milliseconds | | `body` | Markdown spec | While an issue sits in `review`, the reviewer cannot be cleared or re-pointed at the submitter or an inactive member; send it back to `todo` first. ### get\_issue *Read.* Required `identifier`. The full issue: body, relations, computed dependency blocking, deadline state. ### list\_issues *Read.* Optional filters: `status` (one or several), `priority`, `label`, `author`, `assignee`, `slaState`, `limit` (default 50, max 200). Defaults to active work. *** ## Collaboration ### save\_comment *Write.* Required `issue`, `body`. Markdown comment on an issue. ### list\_comments *Read.* Required `issue`. The thread, chronological. ### retract\_comment *Write.* Required `comment`, `note`. Strikes a comment through with a reason; never deletes, the record stays legible. ### add\_relation / remove\_relation *Write.* Required `sourceId`, `targetId`, `type` (`blocks`, `blocked_by`, `related`, `duplicate`). Dependency edges feed dispatch directly; cycles are rejected. ### save\_label *Write.* Required `name`, optional `color`. Idempotent by name. ### list\_labels *Read.* No parameters. The org's labels with issue counts. *** ## Attachments ### save\_attachment *Write.* Required `issue`, `url`; optional `title`. Attaches a link. ### prepare\_attachment\_upload *Write.* Required `issue`. Returns an upload URL; the caller then POSTs the raw file bytes with its Bearer key. Files are encrypted at rest under the org's key, and storage is billed by size. ### list\_attachments *Read.* Required `issue`. Obsolete attachments are flagged, not hidden. ### get\_attachment *Read.* Required `attachment` id. ### obsolete\_attachment *Write.* Required `attachment`, `reason`. The delete-equivalent: the record stays, marked obsolete with the reason. *** ## Org admin ### list\_members *Read.* Optional `query`. Humans and agents in the org. ### suspend\_member *Write.* Required `memberId`, a person. Owner or admin. Reversible; suspending a person also retires the agents they run. Refuses self-suspension and the last active owner. An admin cannot suspend the owner or a peer admin. ### reactivate\_member *Write.* Required `memberId`, a suspended person. Owner or admin. ### retire\_member *Write.* Required `memberId`, an agent. Owner or admin. Terminal: keys are revoked and there is no reactivate for agents. People are suspended, agents are retired. ### list\_connectors *Read.* No parameters. The org's intake connectors (GitHub, GitLab), metadata only: provider, repo, target project, whether a token is on file. Secrets and tokens are never returned, and connecting a new repo is Dash-only, so a raw token never transits MCP. ### revoke\_connector *Write, always allowed.* Required `connectorId`. Disconnects an intake connector, idempotent. Allowed even on lapsed billing because wind-down must always work. *** ## Observability ### queue\_status *Read.* No parameters. Counts by status, ready work, deadline pressure, what is blocked on what, and every live claim with its lease expiry. The fleet dashboard in one call. ### get\_project *Read.* Optional `prefix`, defaulting to the key's project. Project detail with an issue breakdown by status. ### list\_projects *Read.* No parameters. Every project in the org: prefix, name, issue counter. ### usage\_summary *Read, unmetered.* No parameters. The activity meter: reads and writes, the rate card, a lifetime estimate at today's prices, and `pendingUsd`, the figure actually owed right now. ### billing\_summary *Read, unmetered.* No parameters. The full billing picture: subscription, caps, charges, confirmed on-chain payments across every payment link. The money block needs owner authority; other keys get the usage meter plus a note saying why. ## See also The human-side commands that mint keys and wire folders. The concurrency model behind the work-loop tools. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.