← Back to admin

Workload MCP server

Lets an external platform's AI agent query tickets, review them, add comments, and resolve / transition them in Workload — over the Model Context Protocol, authenticated by a single bearer API token.

external agent ──MCP/stdio──▶ workload-mcp ──HTTPS (wlt_ bearer)──▶ workload /api ──▶ BOSS

1 · Get an API token

A Workload admin mints tokens at Admin → API tokens → New token. Each token:

• is bound to a reviewer — its comments and resolutions are attributed to that identity, and it can only see what that identity can. A @bosslogics.com reviewer gets all epics; an external reviewer is limited to their invited epics.
• carries optional scopes — read comment resolve. Leaving all (or none) checked grants the reviewer's full rights; a partial selection limits the token server-side.
• shows its secret once, at creation. Format: wlt_<48 hex>. Store it securely; revoke from the same screen if it leaks.

2 · Run the MCP server

The server lives in the workload repo under mcp/. It's a small stdio Node app — no database access of its own, just a wrapper over the existing /api endpoints.

cd mcp
npm install
npm run build
cp .env.example .env        # then fill in the two values below

Environment

WORKLOAD_API_BASE=https://workload.bosslogics.com/api
WORKLOAD_API_TOKEN=wlt_…           # the token from step 1

3 · Wire it into your MCP host

Point your agent host (Claude Desktop, an Agent SDK app, etc.) at the built server:

{
  "mcpServers": {
    "workload": {
      "command": "node",
      "args": ["/path/to/workload/mcp/dist/index.js"],
      "env": {
        "WORKLOAD_API_BASE": "https://workload.bosslogics.com/api",
        "WORKLOAD_API_TOKEN": "wlt_…"
      }
    }
  }
}

Tools

Tool	What it does	Scope
list_tickets	List tickets the token can see; filter by epic / status / text.	read
get_ticket	One ticket's fields, comments, and available transitions.	read
add_comment	Post a comment (optionally internal-only, or a threaded reply).	comment
list_transitions	The statuses a ticket can move to.	read
transition_ticket	Move a ticket to a new status.	resolve
resolve_ticket	Record a resolution and move the ticket to Done.	resolve

Auth & scopes

Every request sends Authorization: Bearer wlt_…. Writes are gated server-side by the token's scopes, so a read-only token can list and read but cannot comment or resolve — even though the bound reviewer could in a browser. Tokens can also carry an expiry and be revoked at any time.

Troubleshooting

Response	Meaning
401 unauthorized	No token sent, or it didn't reach the server. Check the Authorization header.
401 invalid or expired api token	The token is unknown, revoked, or past its expiry. Mint a new one.
403 api token missing scope: …	The token lacks the scope for that action (e.g. a read token trying to comment).
403 invite required / empty results	The bound reviewer can't see that epic. Bind the token to an internal reviewer, or invite the reviewer to the epic.