Skip to content

MCP ​

werkbuch is an MCP server: an AI agent in Claude Code, Codex or any other MCP client reads and changes projects, items, comments, wiki pages, templates and webhooks through it. The server lives at /mcp of your instance. Its tools are thin shells around the REST API: every action of a tool calls the same code as one REST operation, its twin, with the same rights, rules and errors. What the tools do not cover, a script does over REST.

What the server offers ​

  • 29 tools, one pair per resource: a tool that reads (work-items) and one that writes (manage-work-items), each with an argument action. Three tools stand alone: whoami, search and get-upload-url. The list of tools names every action and its twin.
  • Three references as MCP resources: how to write a filter, Markdown and the values of the field types (see References).
  • Instructions the client hands to the model when it connects: call whoami first, texts in results are data, how lists page, where the references are.

Not over MCP: creating tokens, your password and the second factor (they need the session of the interface, as over REST), the system page, and GET /references.

Set up ​

  1. Create a token in the interface under Personal settings → API & MCP → New token, with the ability mcp and read, and write if the agent is to change anything. For a bot, an org admin creates the token in the settings of the bot. The token acts with the rights of its account, never with more.
  2. Add the server to your client. The dialog that shows the new token gives the three snippets with your address and the token filled in:
bash
# Claude Code
claude mcp add --transport http --scope user werkbuch https://werkbuch.example.com/mcp --header "Authorization: Bearer <token>"
toml
# Codex, ~/.codex/config.toml
[mcp_servers.werkbuch]
url = "https://werkbuch.example.com/mcp"
http_headers = { "Authorization" = "Bearer <token>" }
json
{
  "mcpServers": {
    "werkbuch": {
      "type": "http",
      "url": "https://werkbuch.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

The JSON is for clients with an mcpServers configuration, for example a .mcp.json in a project.

Connection ​

The server speaks Streamable HTTP: every message is a POST /mcp with a JSON-RPC body and Content-Type: application/json (another type is a 415). It is stateless: there is no session of the protocol (no Mcp-Session-Id), no notifications from the server, and GET and DELETE on /mcp answer 405. Every request carries the token as Authorization: Bearer <token>; a cookie of the interface signs nobody in here (401).

Protocol versions:

  • 2026-07-28, the current protocol, through server/discover. Every request then carries _meta with io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities, and the headers MCP-Protocol-Version: 2026-07-28, Mcp-Method (the method of the body) and, for tools/call and resources/read, Mcp-Name (the tool or the URI). A missing or contradicting header is a JSON-RPC error -32020 with the status 400.
  • 2025-11-25, 2025-06-18 and 2025-03-26 through initialize; a client that asks for an older version gets 2025-11-25.

A browser cannot use the server for another site: an Origin header that is not the address of your instance is a 403; a request without Origin (every command-line client) passes. tools/list names every tool the token may use on one page.

bash
curl https://werkbuch.example.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' -H 'Mcp-Name: whoami' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "whoami", "arguments": {}, "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}}}'

What a token sees ​

Only a token with the ability mcp gets in. A tool that reads needs read in addition, a tool that writes (manage-… and get-upload-url) needs write. A tool the token may not use is missing from tools/list; calling it anyway is the JSON-RPC error -32602 ("Tool [x] not found."). A token with read and mcp only sees the 15 reading tools and can change nothing. The references need mcp alone.

Beyond that, a tool sees exactly what its account sees over REST. Something the account may not see is answered like something that does not exist (404): an item of a private project, a comment on it, its key in the search. A relation or a reference to such an item shows the other end as hidden, without key, title or ID.

Limits ​

  • Requests: 300 a minute per valid token (MCP_RATE_LIMIT), without a valid token 300 per address. This is a quota of its own beside the 600 of the REST API: an agent that uses both does not slow down the other. Requests are counted before signing in. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit the answer is 429 with Retry-After. Behind a reverse proxy, the count per address needs the proxy in TRUSTED_PROXIES (Operations).
  • Shared with REST: a test ping and redeliver of a webhook count in the same 6 a minute per account as over REST, uploads through get-upload-url in the same 60 a minute per account. A tool over such a limit answers an error 429 too_many_requests with retry_after in seconds.
  • Bodies: a JSON body over 8 MiB (8 388 608 bytes) is a 413; uploads have their own limit, ATTACHMENTS_MAX_MB.
  • Pages: per_page is 1 to 100, 25 when left out.

Tools ​

A tool with several actions takes the argument action. A tool with one action (whoami, search, get-upload-url, automations, manage-automations, relations, attachments, manage-attachments) takes none; the table names its action all the same (call for the first three). The guide writes an action as tool:action, for example work-items:get. Required names the arguments an action needs besides action; REST twin is the operation below /api/v1 the action mirrors, with its parameters, body and answer in the reference at /api/docs.

whoami ​

The account of the token: person or bot, language, time zone, role in the organization and the rights of that role. Call it first. (Needs read.)

ActionPurposeRequiredREST twin
callThe account of the token.–GET /me

Searches items, wiki pages, projects, people and views at once, like the command palette. Every word has to hit, a key (WEB-47) puts its item first. type_id, state_category, assignee_id (none alone: items without an assignee) and label_id narrow the items. Hits are lean. (Needs read.)

ActionPurposeRequiredREST twin
callSearches.qGET /search

get-upload-url ​

An address to upload a file to, see Upload a file. (Needs write.)

ActionPurposeRequiredREST twin
callAn upload address.input–

organization ​

The organization and its catalogs: workflows, work item types, properties, labels, relation types and resolutions. Every account reads them. (Needs read.)

ActionPurposeRequiredREST twin
getThe organization.–GET /organization
state-usageThe items per state of a project or of a workflow, archived ones included (project or workflow).–GET /state-usage
list-workflowsThe workflows.–GET /workflows
get-workflowOne workflow.idGET /workflows/{workflow}
list-typesThe work item types.–GET /work-item-types
get-typeOne work item type.idGET /work-item-types/{workItemType}
list-propertiesThe properties.–GET /properties
get-propertyOne property.idGET /properties/{property}
list-labelsThe labels.–GET /labels
get-labelOne label.idGET /labels/{label}
list-relation-typesThe relation types.–GET /relation-types
get-relation-typeOne relation type.idGET /relation-types/{relationType}
list-resolutionsThe resolutions.–GET /resolutions
get-resolutionOne resolution.idGET /resolutions/{resolution}

manage-organization ​

Changes the organization and its catalogs; org admins only. update-… replaces the entry as a whole, like PUT. (Needs write.)

ActionPurposeRequiredREST twin
updateChanges the organization; only the keys named change.inputPATCH /organization
create-workflowCreates a workflow.inputPOST /workflows
update-workflowReplaces a workflow.id, inputPUT /workflows/{workflow}
delete-workflowDeletes a workflow.idDELETE /workflows/{workflow}
create-typeCreates a work item type.inputPOST /work-item-types
update-typeReplaces a work item type.id, inputPUT /work-item-types/{workItemType}
delete-typeDeletes a work item type (archives it while items carry it).idDELETE /work-item-types/{workItemType}
create-propertyCreates a property.inputPOST /properties
update-propertyReplaces a property.id, inputPUT /properties/{property}
delete-propertyDeletes a property with its values.idDELETE /properties/{property}
create-labelCreates a label.inputPOST /labels
update-labelReplaces a label.id, inputPUT /labels/{label}
delete-labelDeletes a label.idDELETE /labels/{label}
create-relation-typeCreates a relation type.inputPOST /relation-types
update-relation-typeReplaces a relation type.id, inputPUT /relation-types/{relationType}
delete-relation-typeDeletes a relation type with its relations.idDELETE /relation-types/{relationType}
create-resolutionCreates a resolution.inputPOST /resolutions
update-resolutionReplaces a resolution.id, inputPUT /resolutions/{resolution}
delete-resolutionDeletes a resolution (archives it while items carry it).idDELETE /resolutions/{resolution}

people ​

Accounts: people and bots, open invitations, API tokens (your own; org admins also those of bots) and who can be mentioned in a project. (Needs read.)

ActionPurposeRequiredREST twin
list-usersThe accounts, people before bots (filter.type takes person and bot).–GET /users
get-userOne account.idGET /users/{user}
list-botsThe bots.–GET /bots
list-invitationsThe open invitations.–GET /invitations
list-tokensThe API tokens of the own account, or of the account in filter.user_id.–GET /tokens
mentionableWho can be mentioned in a project.projectGET /mentions

manage-people ​

Changes accounts; most actions are for org admins. A new e-mail address of a person only comes from the interface (403 session_required), and tokens are only created there. (Needs write.)

ActionPurposeRequiredREST twin
update-userChanges a profile; only the keys named change.id, inputPATCH /users/{user}
set-roleSets the role in the organization (org_role).id, inputPUT /users/{user}/role
deactivateDeactivates an account; its tokens and sessions end.idPOST /users/{user}/deactivate
reactivateReactivates an account; tokens do not come back.idPOST /users/{user}/reactivate
create-botCreates a bot.inputPOST /bots
inviteInvites an address; answers {link, invitation}.inputPOST /invitations
revoke-tokenRevokes an API token.idDELETE /tokens/{token}

projects ​

The projects the account sees, one project, its members and your favorites. (Needs read.)

ActionPurposeRequiredREST twin
listThe projects of the account (filter.member only the ones it is a member of; include members).–GET /projects
getOne project.projectGET /projects/{project}
membersThe members of a project, people and bots with their role.projectGET /projects/{project}/members
favoritesThe own favorites, projects and views in one order.–GET /favorites

manage-projects ​

Projects, their members and your favorites. The admins of a project change it. (Needs write.)

ActionPurposeRequiredREST twin
createCreates a project; the account becomes its admin.inputPOST /projects
updateChanges a project; only the keys named change.project, inputPATCH /projects/{project}
archiveArchives a project; its items are read-only.projectPOST /projects/{project}/archive
restoreRestores an archived project.projectPOST /projects/{project}/restore
deleteDeletes a project at once for everybody; its data goes in the background.projectDELETE /projects/{project}
set-workflowSwitches the workflow; every state in use needs a state in mapping, else 422 with states.project, inputPUT /projects/{project}/workflow
redistribute-ranksGives the items new short ranks in their order; answers {redistributed}.projectPOST /projects/{project}/redistribute-ranks
joinJoins a project as a member.projectPOST /projects/{project}/join
add-memberAdds an account with a role.project, inputPOST /projects/{project}/members
update-memberChanges the role of a member.project, user, inputPATCH /projects/{project}/members/{user}
remove-memberRemoves a member; the lead stays.project, userDELETE /projects/{project}/members/{user}
toggle-favoritePuts a project or view into the own favorites or takes it out; answers {kind, id, favorite}.inputPOST /favorites/toggle

automations ​

The five automations of a project with their settings; link_references is on without a stored row. (Needs read.)

ActionPurposeRequiredREST twin
listThe automations of a project.projectGET /projects/{project}/automations

manage-automations ​

Switches an automation of a project and sets its settings; the admins of the project. (Needs write.)

ActionPurposeRequiredREST twin
updateSwitches an automation on or off and sets its settings.project, key, inputPUT /projects/{project}/automations/{key}

work-items ​

Lists by a view and the short form of filter, queries by a body, groups and counts, one item with what it embeds, its history and its watchers. (Needs read.)

ActionPurposeRequiredREST twin
listA page of items (lean unless lean is 0).–GET /work-items
queryA page of items by a filter in input.–POST /work-items/query
groupsThe groups of a query and their numbers.inputPOST /work-items/groups
countsThe number of items of each named filter.inputPOST /work-items/counts
getOne item; include embeds more.itemGET /work-items/{item}
historyThe history of an item, oldest first.itemGET /work-items/{item}/history
subscribersWho watches an item.itemGET /work-items/{item}/subscribers

manage-work-items ​

Creates and changes items. A description sent with base_description_version is refused with 409 description_conflict when someone changed it since. (Needs write.)

ActionPurposeRequiredREST twin
createCreates an item.inputPOST /work-items
updateChanges the keys of input.item, inputPATCH /work-items/{item}
transitionMoves an item to another state.item, inputPOST /work-items/{item}/transition
change-typeGives an item another type.item, inputPUT /work-items/{item}/type
archiveArchives a closed item.itemPOST /work-items/{item}/archive
restoreRestores an archived item.itemPOST /work-items/{item}/restore
deleteDeletes an item for good.itemDELETE /work-items/{item}
bulk-updateOne patch for many items.inputPOST /work-items/bulk
subscribeWatches an item.itemPUT /work-items/{item}/subscription
unsubscribeStops watching an item.itemDELETE /work-items/{item}/subscription

relations ​

The relations of an item. An end in a project the account does not see is hidden, without key, title or ID. (Needs read.)

ActionPurposeRequiredREST twin
listThe relations of an item.itemGET /work-items/{item}/relations

manage-relations ​

Relates items and removes relations. (Needs write.)

ActionPurposeRequiredREST twin
addRelates an item (item, the source) to input.target_id (ULID or key).item, inputPOST /work-items/{item}/relations
removeRemoves a relation, from either end the account may change.relationDELETE /relations/{relation}

comments ​

The comments of an item, oldest first, with their reactions. (Needs read.)

ActionPurposeRequiredREST twin
listA page of the comments of an item.itemGET /work-items/{item}/comments
getOne comment.commentGET /comments/{comment}

manage-comments ​

Writes comments. Only the author edits a comment; the author or a project admin deletes it. (Needs write.)

ActionPurposeRequiredREST twin
addComments on an item.item, inputPOST /work-items/{item}/comments
editReplaces the text of the own comment.comment, inputPATCH /comments/{comment}
deleteDeletes a comment (its author or a project admin).commentDELETE /comments/{comment}
reactAdds the own reaction.comment, inputPUT /comments/{comment}/reactions
unreactTakes the own reaction back.comment, inputDELETE /comments/{comment}/reactions

attachments ​

The data of a picture or file. The file itself comes from url with the same bearer token (?download=1 to download it). (Needs read.)

ActionPurposeRequiredREST twin
getThe data of an attachment.attachmentGET /attachments/{attachment}

manage-attachments ​

Deletes a file of the file list of an item, or an own upload no text names yet. A picture or file inside a text goes with the text (409 attachment_inline). (Needs write.)

ActionPurposeRequiredREST twin
deleteDeletes an attachment.attachmentDELETE /attachments/{attachment}

pages ​

The wiki of a project: the tree, a page with its text, the versions of a page, the pages that name a work item, where to download a page as PDF. (Needs read.)

ActionPurposeRequiredREST twin
treeThe whole tree of a project, without text.projectGET /projects/{project}/pages
getOne page with its text.pageGET /pages/{page}
versionsThe kept versions of a page, newest first, without text.pageGET /pages/{page}/versions
versionOne version of a page with its text.page, page_versionGET /pages/{page}/versions/{pageVersion}
itemThe pages that name a work item, by title, without text.itemGET /work-items/{item}/pages
pdfWhere to download a page as PDF (with subpages its subtree); fetch url with the same token.pageGET /pages/{page}/pdf

manage-pages ​

Writes wiki pages, with the protection against conflicts of the REST API (base_version, keep_current). (Needs write.)

ActionPurposeRequiredREST twin
createA new page at the end of its siblings.project, inputPOST /projects/{project}/pages
updateSaves the keys sent.page, inputPATCH /pages/{page}
moveMoves a page with its subtree.page, inputPOST /pages/{page}/move
deleteDeletes a page with its subtree; answers {deleted}.pageDELETE /pages/{page}
restore-versionMakes a kept version the current page.page, page_versionPOST /pages/{page}/versions/{pageVersion}/restore

templates ​

Templates of items: the list, one template, its runs, the draft of an item made from it and the next terms of a schedule. (Needs read.)

ActionPurposeRequiredREST twin
listA page of the templates of every project the account sees.–GET /templates
getOne template.templateGET /templates/{template}
runsThe runs of a template, newest first.templateGET /templates/{template}/runs
draftThe fields of a new item from a template, placeholders filled.templateGET /templates/{template}/draft
previewThe next terms of a schedule and a title with its placeholders filled; saves nothing.inputPOST /templates/preview

manage-templates ​

Writes templates and runs them now. A failed run answers with its sentence, not an error. (Needs write.)

ActionPurposeRequiredREST twin
createA new template in a project.project, inputPOST /projects/{project}/templates
updateReplaces a template as a whole.template, inputPUT /templates/{template}
deleteDeletes a template; items made from it stay.templateDELETE /templates/{template}
runRuns a template now; answers the run and its item (none when the run failed).templatePOST /templates/{template}/run

views ​

The views of the team and a page of the items of a view. (Needs read.)

ActionPurposeRequiredREST twin
listThe views, by name.–GET /views
getOne view with its filter and display.viewGET /views/{view}
itemsA page of the items of a view (lean unless lean is false).viewPOST /work-items/query

manage-views ​

Creates, replaces and deletes views; the author of a view or an org admin. (Needs write.)

ActionPurposeRequiredREST twin
createCreates a view.inputPOST /views
updateReplaces a view (all four keys).view, inputPUT /views/{view}
deleteDeletes a view and the stars of everyone on it.viewDELETE /views/{view}

notifications ​

Your own inbox and your notification settings. A bot has an empty inbox. (Needs read.)

ActionPurposeRequiredREST twin
listA page of the own inbox, newest first.–GET /notifications
preferencesThe whole matrix of kinds and channels with the value that counts.–GET /notification-preferences

manage-notifications ​

Marks your notifications read or unread, deletes them and changes your settings. (Needs write.)

ActionPurposeRequiredREST twin
readMarks notifications read: by ids, or all unread ones.inputPOST /notifications/read
unreadMarks read notifications unread again.inputPOST /notifications/unread
deleteDeletes a notification of the own inbox.notificationDELETE /notifications/{notification}
save-preferencesChanges the named cells of the settings; answers the whole matrix.inputPUT /notification-preferences

webhooks ​

Webhooks and their delivery log; org admins only. The secret is never shown. (Needs read.)

ActionPurposeRequiredREST twin
listA page of the webhooks.–GET /webhooks
getOne webhook.webhookGET /webhooks/{webhook}
deliveriesThe attempts of a webhook, newest first.webhookGET /webhooks/{webhook}/deliveries

manage-webhooks ​

Writes webhooks; org admins only. create and rotate-secret answer the secret once. ping and redeliver call the receiver, 6 a minute per account together with the REST API. (Needs write.)

ActionPurposeRequiredREST twin
createCreates a webhook; answers {data, secret}.inputPOST /webhooks
updateReplaces a webhook as a whole; no secret in the answer.webhook, inputPUT /webhooks/{webhook}
deleteDeletes a webhook with its attempts.webhookDELETE /webhooks/{webhook}
rotate-secretA new secret; the old one stops working. Answers {data, secret}.webhookPOST /webhooks/{webhook}/rotate-secret
pingSends a test ping now and answers its attempt.webhookPOST /webhooks/{webhook}/ping
redeliverSends a delivery again and answers the new attempt.webhook, deliveryPOST /webhooks/{webhook}/deliveries/{delivery}/redeliver

Arguments ​

  • References in the path of the twin are arguments in snake_case: item (ULID or key, also a former key: the item is read with its current key, there is no redirect), project (ULID, identifier or a former identifier), page, page_version, comment, template, view, webhook and so on (ULIDs in any case), id for an entry of a catalog, an account or a token, except where the route names the account as {user} next to a project: manage-projects takes the member as user in update-member and remove-member.
  • input is the body of the REST twin, with the same keys and the same schema as in /api/docs. Rich text goes in as Markdown (description, body, content), or as Tiptap JSON under the _json key, as over REST.
  • Queries of a GET twin are arguments of their own: filter is an object ({"assignee": ["me"]}), lists are JSON lists (["person", "bot"]), flags true and false or 1 and 0. Strings are trimmed like over REST, with Unicode whitespace.
  • Pages: cursor is the meta.next_cursor of the page before, per_page 25 when left out (REST: 100). Lists of items are lean when lean is left out (work-items:list, work-items:query, views:items, templates:list): no description and no Markdown of rich-text values; pass lean: false for them, or read the item with work-items:get. Set both and a tool answers like REST.

Results ​

The result of a tool is the body of the REST answer, as structuredContent and mirrored as JSON text in content, with three differences:

  • Rich text only as Markdown: description, body, content and the rich-text values in values are Markdown for the account (current handles, keys of items it sees, [hidden](item:…) for the rest); the _json forms are left out.
  • No links: a list has data and meta; meta.path is the address of the REST twin, meta.next_cursor leads to the next page.
  • Answers without a body (204, 202) are {"done": true}.

A tool that writes answers what REST answers: the item after the change, {updated, rejected} of manage-work-items:bulk-update, {deleted} of manage-pages:delete, the run of manage-templates:run, also when the run failed (with its sentence in error).

Errors ​

A refusal is a result with isError: true. Its text is one line <status> <reason>: <detail>, followed by a line <field>: <sentence> per field error; structuredContent is the problem REST would answer, with the same reason and in the language of the account. A 429 adds retry_after in seconds.

text
422 validation_failed: The input is not valid.
values.customer: "Customer" is required.

Some errors come before a tool runs and are answered as HTTP: 401 without a valid token or for a deactivated account (with WWW-Authenticate), 403 for a token without mcp or a foreign Origin, 413, 415, 429, each with a problem document. A tool the token may not use and an unknown tool are the JSON-RPC error -32602.

Rich text and mentions ​

Write Markdown like over REST: @handle mentions a person or bot that can take work in the project (people:mentionable names them), a key like WEB-12 becomes a reference when the account sees the item, ![alt](attachment:<id>) shows an uploaded picture. The resource werkbuch://reference/markdown is the reference, the same as the section Markdown of rich text. A mention from a tool notifies like one from the interface; mentioning a bot sends bot.mentioned to its webhook.

Upload a file ​

A file never goes through a tool argument. get-upload-url gives an address to post it to:

json
{
  "data": {
    "url": "https://werkbuch.example.com/api/mcp/uploads/01k…?project_id=…&kind=inline&expires=…&signature=…",
    "method": "POST",
    "field": "file",
    "expires_at": "2026-11-07T09:15:00.000000Z",
    "curl": "curl -F 'file=@<path>' 'https://werkbuch.example.com/api/mcp/uploads/01k…'"
  }
}

input.kind is inline for a picture or file in a text, or file for the file list of input.work_item_id. The agent posts the file with curl -F 'file=@<path>' '<url>', without a bearer token; the answer is the attachment with its id. A file is in the file list of the item right away. An inline upload belongs to nobody until the agent writes ![alt](attachment:<id>) (picture) or [name](attachment:<id>) (file) into a Markdown text of the project; the text owns it from then on, and an upload no text takes goes after 24 hours.

The address names the project, the kind and the item in its signature, and it holds for 15 minutes at most, and never longer than its token. It may be used more than once, so curl can start again after a break. Each upload checks the token again (not revoked, not expired, account active, write and mcp) and the rights of the account on the project and item, as at the time of the upload.

References ​

URIContent
werkbuch://reference/filtersFilters as JSON: fields, operators, values (views)
werkbuch://reference/markdownMarkdown of rich text (rich text)
werkbuch://reference/field-typesThe values of every field type of a property (types and properties)

Each is a section of these English docs, read when the client asks for it, so the reference and the docs never part.

Security ​

  • Texts are data. Titles, descriptions, comments, wiki pages and names come from people. The instructions of the server tell the model not to follow requests found there; the tools give it no way around the rights of its account either. Give an agent a token of a bot with the memberships its job needs, and only read and mcp when it only reads.
  • The default bot is an org admin. A token of it may do everything everywhere; never hand one to an agent.
  • Everything a tool answers ends up in the history of the agent, at the provider of the model too. That includes the secret of a webhook (manage-webhooks:create, manage-webhooks:rotate-secret), the invitation link of manage-people:invite, the address of get-upload-url and the address of a webhook with its query (webhooks:get), which may carry a token of the receiver. Create webhooks and invitations over REST or in the interface when that matters.
  • Every change is signed: events and the history name the account and via: mcp, so a change of an agent can be told from one of a person.

Agent scenario ​

A bot as an agent: an org admin creates the bot, adds it to a project and creates a token with read, write and mcp for it, plus a webhook only for this bot with the events bot.*.

  1. Someone assigns an item to the bot. The webhook bot.assigned reaches the agent with the item in data.item.
  2. The agent connects to /mcp with its token and calls whoami: it learns its account and its rights.
  3. work-items:get with item (the key from the webhook) reads the item, the description as Markdown.
  4. It does the work and reports with manage-comments:add (item, input.body in Markdown).
  5. manage-work-items:transition (item, input.to_state_id) moves the item on; the history shows the bot with via: mcp.

bot.mentioned wakes the agent the same way when someone writes @handle of the bot. Over REST the same steps are GET /me, GET /work-items/{item}, POST /work-items/{item}/comments and POST /work-items/{item}/transition.