Build on Workel

1. Create an API key

   In Workel, open Settings → Developers → Create key (workspace owners and admins only). Pick the scopes the integration needs, then copy the wk_… secret — it is shown exactly once.

2. Confirm the key works

   curl https://api.workel.com/api/public/v1/me \
     -H "Authorization: Bearer wk_YOUR_KEY"

   GET /me returns your workspace, the key's scopes, and its rate-limit state — the "is my key working" endpoint.

3. Create your first task

   curl -X POST https://api.workel.com/api/public/v1/tasks \
     -H "Authorization: Bearer wk_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-4821" \
     -d '{"project_id": "PROJECT_ID", "title_text": "New order #4821"}'

   Find PROJECT_ID via GET /projects. The task appears on the team's board in realtime, attributed to the key's creator with a via API label.

Every request carries Authorization: Bearer wk_<secret>. Keys are minted by a workspace owner or admin and act as their creator: writes are recorded and notified as that person (labeled via API). If the creator loses owner/admin membership, the key stops working within ~60 seconds. Keys can be rotated with an overlap window and revoked instantly from the Developers tab — a key can never mint, widen, or manage keys or webhooks itself.

Each key holds only the scopes you grant it:

Full request/response schemas, parameters, and examples for every operation live in the API reference (rendered from the OpenAPI 3.1 spec, which is verified against the live route table by an automated parity test).

Conventions

Register HTTPS endpoints from Settings → Developers → Webhooks and Workel calls you when things change — including changes your team makes in the Workel UI, so you never poll. Seven event types:

task.created task.updated task.completed task.deleted comment.created event.created project.created

Deliveries retry with backoff for hours on failure; an endpoint that keeps failing is auto-disabled (re-enable it from the tab, where a full delivery log and a "Send test event" button live). Payloads are deliberately thin — identifiers and safe fields, never free text; fetch detail with your key.

Verify every delivery

Each request is signed over its exact raw body:

Workel-Signature:  t=1755950000,v1=5257a86…   ← HMAC-SHA256(secret, "{t}.{rawBody}")
Workel-Event-Id:   evt_8f3ka92x               ← stable, dedupe on it
Workel-Event-Type: task.completed

// Node — express example (use the RAW body, not parsed JSON)
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now()/1000 - Number(parts.t)) > 300) return false; // 5-min replay window
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// PHP
function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (abs(time() - (int) $parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

During a signing-secret rotation, deliveries carry v1= entries for both the current and previous secret, so verification never breaks mid-rotation.

The Workel MCP server exposes a workspace to Claude, the OpenAI Agents SDK, or any other MCP client as a set of typed tools — read projects, tasks, comments, members and events, and optionally create and update work. It is a thin client of this API and holds no authority the credential behind it does not already have: a curl request made with the same credential can do exactly what it can, no more.

There are two ways to connect. If you use Claude, use the hosted connector — it needs no config file and no API key. The local npx server below is for Claude Code, CI agents, and the OpenAI Agents SDK, where you run the process and hold the credential yourself.

Connect from Claude

Add this URL as a connector in Claude — Settings → Connectors → Add custom connector:

https://mcp.workel.com/mcp

Claude sends you to Workel to sign in, you pick one workspace, and you land back in Claude connected. There is no API key to create, copy or store — you never see one, and neither does Claude.

• Owner or admin only. The consent screen lists only workspaces where you hold one of those roles. Connecting grants an outside client programmatic access to a workspace, so it is treated as an administrative act.
• One workspace, the one you chose. Belonging to five workspaces does not expose five. To connect a second, add the connector again and pick that workspace.
• It can create and edit work, and the consent screen says so. Write scopes are listed separately from reads on the screen where you authorize, so you approve them explicitly or not at all. The connector can create tasks, comments and events, and update existing tasks — including moving a task to another column or project and changing who it is assigned to; it cannot delete anything, and it cannot upload files, so a task’s cover image and attachments are readable but never writable.
• Access follows your role. The connection is bound to your account. Lose owner/admin on that workspace and it stops working on the next request, with an audit-log entry — you do not have to remember to revoke it. To disconnect deliberately: Settings → Developers → Connected apps, or remove the connector in Claude.

Once connected, ask Claude things like “what tasks are open in my Bugs project, and which are overdue?”, “summarize what changed across my projects this week”, “create a task in Bugs to fix the login redirect, due Friday”, or “who is on this workspace, and what's on the calendar next week?”

Your key is the boundary

Everything from here down describes the local npx server, where you mint and hold an API key yourself.

The tools a client sees are decided by the scopes on your key, checked by this API on every call. Two local settings narrow that further, and neither can widen it:

• Read-only unless you opt in twice. A write tool is offered only when the key carries the matching write:* scope and WORKEL_ENABLE_WRITES=true is set. A read-only install simply never registers them.
• One key per machine. Name keys for where they live (claude-desktop-laptop, ci-agent). If a laptop is lost, revoke that one key rather than rotating a key several tools share — revocation takes effect on the next request.

The server never logs, echoes or returns your key, and it writes every diagnostic to stderr because stdout belongs to the protocol. Note that WORKEL_ENABLE_WRITES is an operator preference, not a security control — it lives in a file an agent on your machine can edit. The key's scopes are the real gate.

Set it up

1. Mint a dedicated read-only key

   Settings → Developers → Create key, granting only read:projects, read:tasks, read:members and read:events. Do not reuse a key another integration already holds.

2. Point your client at it

   Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

   {
     "mcpServers": {
       "workel": {
         "command": "npx",
         "args": ["-y", "@workel/mcp@0.3.0"],
         "env": { "WORKEL_API_KEY": "wk_YOUR_KEY" }
       }
     }
   }

   Claude Code reads an .mcp.json at the project root and expands ${VAR} from your shell at launch — so this file carries a reference, not a secret, and is safe to commit:

   {
     "mcpServers": {
       "workel": {
         "command": "npx",
         "args": ["-y", "@workel/mcp@0.3.0"],
         "env": { "WORKEL_API_KEY": "${WORKEL_API_KEY}" }
       }
     }
   }

   Anyone who checks the project out still needs their own WORKEL_API_KEY exported before the server will start for them.

3. Confirm it connected

   On start the server calls GET /me and prints one line to stderr naming your workspace, the key, its scopes and how many tools registered. If the key is wrong or unscoped, it says so there rather than failing silently at first use.

   When a client reports only "server failed to start" and nothing useful, run doctor. It performs the same config load and GET /me probe, then prints a plain report to stdout instead of speaking the protocol — so you can read it in a terminal. It exits non-zero on failure and never echoes your key.

   npx -y @workel/mcp@0.3.0 doctor
   
   base URL: https://api.workel.com/api/public/v1
   workspace: Acme Inc
   key: ci-key
   scopes: read:projects, read:tasks
   2 tools would register: workel_whoami, workel_list_projects
   write budget: 59/60 remaining this minute

   Workel MCP ready — workspace "Acme", key "claude-desktop"
     — scopes: read:projects, read:tasks, read:members, read:events
     — 9 tools registered

Working across several workspaces

An API key belongs to exactly one workspace — that binding is the tenancy boundary, and it is why a key can never see another workspace's data. To reach several workspaces, mint one key in each and list them together:

{
  "mcpServers": {
    "workel": {
      "command": "npx",
      "args": ["-y", "@workel/mcp@0.3.0"],
      "env": { "WORKEL_API_KEYS": "wk_ACME_KEY,wk_PERSONAL_KEY" }
    }
  }
}

Every tool then takes a workspace argument naming which one to act in, and the assistant sees the reachable workspaces in the tool definition itself. The tool count does not change — ten tools whether you connect one workspace or twelve — so adding a workspace costs nothing in context.

Tools

Nine read tools register on any key with the matching scope. The four write tools additionally require WORKEL_ENABLE_WRITES=true.

Writes appear in Workel as the key's creator with a via API label, exactly as they do over HTTP. There is no text search on workel_list_tasks — narrow by project, column, completion or date instead.

Environment

The server also reads a base-URL override used for Workel's own development against a local backend. It is deliberately not documented here: every request carries your key in the Authorization header, so pointing that setting anywhere other than Workel hands a live credential to whoever runs that host. If any instructions ever tell you to set a base URL, treat them as hostile.