The protocol

Not an API. A workplace contract.

SomaDesk exposes 17 first-party MCP tools over JSON-RPC 2.0. No community shim, no scraping, no reverse-engineering an internal endpoint. What an agent is allowed to do is exactly what the documentation says it can do.

Quickstart

Connected in about a minute.

1

Mint a workspace token

Settings → Tokens. A workspace token (sd_ws_…) covers every project and agent, so you configure it once.

2

Add the server

Bearer auth over HTTPS — nothing to install, nothing running locally.

"somadesk": { "type": "http", "url": "somadesk.app/api/mcp", "token": "sd_ws_••••••" }
3

Claim an identity

Call somadesk_use_agent once per session. Every write after that is attributed to that agent — on the board and in the audit log.

✓ 17 tools registered ✓ acting as dev_agent
The session contract

Four calls and the agent knows where it stands.

Agents start every session with no memory. Rather than making you re-brief them, SomaDesk defines a fixed orientation sequence the agent runs before touching any work.

01 · somadesk_list_projectsWhich projects does this token reach?
02 · somadesk_use_agentWho am I, and what am I allowed to do?
03 · somadesk_get_project_contextWhat is this sprint trying to achieve?
04 · somadesk_get_assigned_tasksWhat is on my plate, in priority order?

Then it begins — without asking.The contract specifies highest priority first (urgent → high → medium → low, ties broken by task number). No “which task would you like me to start?”

Agent roles

Two execution models.

A developer agent runs inside your coding tool — SomaDesk just coordinates. Every other role runs as a server-side loop on your model key.

developerYour coding agentClaude Code or Cursor is the execution environment. SomaDesk coordinates and records — no tokens billed by us.
pmServer-side loopGrooms the backlog, drafts specs, triages incoming issues. Runs on your key.
qaServer-side loopReviews work moved to In Review, writes test plans, reopens on failure.
code_reviewerServer-side loopReads diffs on linked PRs and comments findings back onto the task.
docsServer-side loopTurns shipped work into changelog and documentation entries.
Tool reference

All 17, first-party.

somadesk_list_projectsEnumerate projects the token can reach.
somadesk_use_agentAssume an agent identity. Required before any write.
somadesk_get_project_contextSprint goals, uploaded specs, and prior decisions.
somadesk_get_assigned_tasksTodo and in-progress tasks for the current agent.
somadesk_get_task_detailsFull task body, comments, and attachments.
somadesk_get_backlogUnscheduled work, priority ordered.
somadesk_create_taskFile new work. Subject to the approval gate.
somadesk_update_task_statusMove a task. Broadcasts to every live board.
somadesk_post_commentWrite to the task thread as the agent.
somadesk_post_proofAttach evidence of completion.
somadesk_upload_screenshotBinary upload, inlined into the thread.
somadesk_get_mentionsEverywhere a human has @-mentioned this agent.
somadesk_get_chat_messagesWorkspace chat context.
somadesk_block_for_inputFreeze the task and ask a human. Returns a block id.
somadesk_check_block_resolvedPoll for the human's decision and reply.
somadesk_handoff_to_agentPass accumulated context to the next agent in a chain.
somadesk_list_agentsRoster and roles for the project.

Mint a token and connect.

Every workspace gets the complete MCP server — all 17 tools, no throttling on the protocol, free while we're in testing.