tool reference

The spirby mcp server gives agents typed access to feedback boards over the Model Context Protocol. Tools are scope-gated — a read key never sees a write tool, even by name.

Eighteen tools total: one self-test (whoami), seven read tools, ten write tools. All schemas use json-schema (draft 2020-12) and are emitted directly from the source-of-truth zod schemas in @spirby/mcp.

read tools

tool	required scope	what it does
whoami	read	Return the active token’s identity: organization id, scope, and remaining rate-limit budget.
list_boards	read	List every feedback board in the workspace.
search_posts	read	Search posts on a board.
get_post	read	Fetch a single post by id, including body, status, vote count, and tag ids.
list_changelog	read	List a board’s changelog entries.
list_contacts	read	List end-user contacts (also called ‘customers’) in the workspace.
get_contact	read	Fetch a single contact by id with aggregate counts (posts, votes, comments).
list_posts_by_contact	read	List feedback posts attached to a contact across every board, newest first.

write tools

tool	required scope	what it does
create_post	read:write	Create a new feedback post on a board.
update_post	read:write	Update an existing post’s title, status, body, slug, or contact attribution.
vote_post	read:write	Cast a vote on a post on behalf of the user who minted this API key.
unvote_post	read:write	Retract a vote on a post.
create_comment	read:write	Post a comment on a feedback post.
publish_changelog_entry	read:write	Publish a draft changelog entry.
create_contact	read:write	Create a feedback contact.
identify_contact	read:write	Identify or upsert a contact by your system’s user id.
update_contact	read:write	Partially update a contact.
delete_contact	read:write	Delete a contact.

consistency notes

• All ids are opaque strings (ulids under the hood). Pass them around verbatim.
• All write tools share the same billing-readonly gate as the rest api: a trial-expired workspace returns ERR_BILLING_READONLY with a hint pointing the user to billing settings.
• Idempotent writes (vote_post, unvote_post, identify_contact) return the current state without raising, so an agent retry never double-applies.
• tools/list is filtered server-side by the key’s scope. A read key never sees the write tools, even by name.
• MCP inputs are snake_case (e.g. external_user_id); the rest api uses camelCase (e.g. externalUserId). Both surfaces validate the same constraints — the docs for each tool list every refine the schema enforces.