Scrumbo API & MCP server — developer docs

Authentication

Every request needs a personal API key. Create one on your account page — it is shown once, so copy it right away.

Send it as a bearer token on every request:

Authorization: Bearer sbo_your_key_here

REST API

The API is mounted at https://scrumbo.com/api/v1 and returns JSON. A key has exactly your access: it can only reach projects and boards you own, are a member of, or administer.

Method	Path	Description	Access needed
GET	`/projects`	List projects you can access	Any key
GET	`/projects/:token/boards`	List boards in a project	Viewer
GET	`/boards/:boardid`	Get a board with its statuses and stories	Viewer
GET	`/boards/:boardid/statuses`	List a board's statuses	Viewer
GET	`/boards/:boardid/stories`	List stories on a board, optionally filtered by status or assignee	Viewer
GET	`/boards/:boardid/stories/:storyid`	Get a single story	Viewer
POST	`/boards/:boardid/stories`	Create a story	Editor
PATCH	`/boards/:boardid/stories/:storyid`	Update a story's fields	Editor
POST	`/boards/:boardid/stories/:storyid/status`	Change a story's status	Editor or contributor
DELETE	`/boards/:boardid/stories/:storyid`	Delete a story	Editor
POST	`/boards/:boardid/stories/:storyid/comments`	Add a comment to a story	Commenter
Account, billing & invoices
GET	`/account`	Get your account: plan, free-plan usage limits and billing details	Any key
GET	`/invoices`	List your invoices	Any key
GET	`/invoices/:invoiceid` · `…/pdf`	Get one invoice's details, or download it as a PDF	Any key
Hour bank
GET	`/projects/:token/hourbank` · `…/transactions`	Get a project's hour-bank settings and current balance, or its transaction ledger	Viewer
POST	`…/hourbank/settings` · `…/entries`	Configure a project's hour bank, or add a purchase/adjustment to it	Project owner
Team
GET	`/team`	List your internal team across every project and feature board you own	Any key
Feature boards
GET	`/featureboards`	List the feature boards you belong to	Board member
POST	`/featureboards`	Create a feature board	Paid plan
GET	`/featureboards/:boardid`	Get a feature board with its features, votes, comments and members	Board member
POST	`…/features` · `…/vote` · `…/comments`	Submit a feature request, vote on one, or add a comment	Board member
PATCH POST DELETE	`…/features/:featureid` · `…/status`	Update, set the status of, or delete a feature request	Board admin
DELETE	`…/comments/:commentid`	Delete a feature comment	Comment author or board admin
POST DELETE	`/featureboards/:boardid/members` · `…/:userid/admin` · `…/:userid/external`	Add, promote/demote, reclassify or remove a board member	Board admin

"Editor or contributor" also covers developers, who may change status but not edit story text.

Example:

curl https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here"

curl -X POST https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"subject": "New story", "story": "Details go here"}'

Parameters

Request bodies are JSON. Every parameter below is accepted by both the REST API and the matching MCP tool.

Path parameters

Name	Type	Required	Description
`:token`	string	Yes	Project token, as returned by GET /projects.
`:boardid`	integer	Yes	Numeric board id, as returned by GET /projects/:token/boards.
`:storyid`	integer	Yes	Numeric story id, unique within its board.

Query parameters

GET /boards/:boardid/stories

Name	Type	Required	Description
`status`	string	No	Return only stories in this status. Capitalisation is ignored when filtering.
`assigned`	string	No	Return only stories with this assignee name. Capitalisation is ignored when filtering.

Story fields (create and update)

POST /boards/:boardid/stories · PATCH /boards/:boardid/stories/:storyid

Name	Type	Required	Description
`subject`	string	On create	Short title, at most 500 characters. Required when creating; longer values are rejected.
`story`	string	No	Story body. HTML is allowed but sanitized server-side, so unsupported tags and attributes are stripped.
`status`	string	No	Must match one of the project's statuses exactly, including capitalisation. When creating, an unknown or omitted status falls back to the board's first status; when updating, an unknown status is rejected.
`assigned`	string	No	Assignee name, free text. This is a label only — it does not link the story to a Scrumbo account.
`requester`	string	No	Name of the person who requested the story, free text.
`scope`	string	No	Short scope label, at most 100 characters. Longer values are rejected.
`comment`	string	No	Legacy free-text field stored on the story itself. It is not shown in the web interface — to add a visible comment, use the comments endpoint below.
`notify`	boolean	No	Email the board's and story's followers about this change. Defaults to false.

Any field not listed here is ignored rather than rejected.
An update must supply at least one of these fields; only the fields you send are changed.
Linking a story to a Scrumbo account (the assignee picker) is not available through the API.

Move a story

POST /boards/:boardid/stories/:storyid/status

Name	Type	Required	Description
`status`	string	Yes	Target status. Must match one of the project's statuses exactly, including capitalisation.
`notify`	boolean	No	Email the board's and story's followers about this change. Defaults to false.

Add a comment

POST /boards/:boardid/stories/:storyid/comments

Name	Type	Required	Description
`comment`	string	Yes	Comment text, plain text. It is escaped before storage, so HTML is shown literally rather than rendered.
`name`	string	No	Author name to show on the comment. Defaults to the name on the API key's account.
`notify`	boolean	No	Email the board's and story's followers about this change. Defaults to false.

Rejected requests return the matching HTTP status (400, 403 or 404) and a JSON body:

{"error": "subject must be at most 500 characters"}

MCP server

Scrumbo ships a standalone MCP server that wraps the REST API as tools, so an MCP-aware assistant such as Claude Desktop or Claude Code can use your boards directly. It needs Node.js 20 or newer.

Download the MCP server (ZIP)

Unpack it and install its dependencies once:

unzip scrumbo-mcp.zip
cd scrumbo-mcp
npm install

Create an API key on your account page and copy it.
Register the server with your MCP client, for example:

{
  "mcpServers": {
    "scrumbo": {
      "command": "node",
      "args": ["/absolute/path/to/scrumbo-mcp/index.js"],
      "env": {
        "SCRUMBO_API_KEY": "sbo_your_key_here",
        "SCRUMBO_API_URL": "https://scrumbo.com/api/v1"
      }
    }
  }
}

Tools:

Description	Access needed
`list_projects`	Any key
`list_boards`, `get_board`, `list_stories`, `get_story`, `list_statuses`	Viewer
`add_comment`	Commenter
`create_story`, `update_story`, `move_story`, `delete_story`	Editor
`get_account`, `list_invoices`, `get_invoice`, `get_invoice_pdf`, `get_team`	Any key
`get_hourbank`, `list_hourbank_transactions`	Viewer
`save_hourbank_settings`, `add_hourbank_entry`	Project owner
`list_feature_boards`, `get_feature_board`, `create_feature`, `vote_feature`, `add_feature_comment`	Board member
`create_feature_board`	Paid plan
`update_feature`, `set_feature_status`, `delete_feature`, `add_feature_board_member`, `set_feature_board_member_admin`, `set_feature_board_member_external`, `remove_feature_board_member`	Board admin
`delete_feature_comment`	Comment author or board admin

Keep in mind

A key has exactly your access — anyone holding it can act as you within that scope, so treat it like a password.
Revoke a key from your account page at any time; anything using it stops working immediately.
The MCP server itself holds no database access — it is a thin HTTP client that is only ever as privileged as the key you give it.