Workel MCP Server

The official Model Context Protocol server for Workel — a thin, stateless client of the Workel Public API v1. It exposes a Workel workspace to AI agents (Claude, the OpenAI Agents SDK, or any other MCP-speaking client) as a small set of well-scoped tools. Every rule that actually matters — what this key can see, what it can write, how fast it can write it — lives in the Workel API itself; this package holds no authority the key doesn't already have. A curl request made with the same key can do exactly what this server can do, no more.

For full per-client setup (Claude Desktop, Claude Code, project-scoped .mcp.json, and the OpenAI Agents SDK), see the Workel developer docs.

Using Claude? You probably don't need this package

Workel runs a hosted MCP server. Add it in Claude under Settings → Connectors → Add custom connector:

https://mcp.workel.com/mcp

You sign in to Workel, pick one workspace, and you're connected. No install, no config file, and no API key — you never see one and neither does Claude. Authorizing requires owner or admin on the workspace you choose, and the connection is re-checked on every request, so losing that role disconnects it without anyone having to remember to revoke a key.

It can read your projects, tasks, comments, events and members — including a task's cover image, attachments and full history — and it can create tasks, comments and events, and update existing tasks: renaming them, changing dates and priority, moving them between columns and projects, and changing who they are assigned to. It cannot delete anything, and it cannot upload files. Read and write permissions are listed separately on the consent screen, so you approve them knowingly rather than discovering them later.

Connecting more than one workspace

One connection covers one workspace, because the credential behind it is bound to that workspace. To reach a second, add the connector again and pick the other workspace — each connection registers separately, so they coexist, and each appears under the name of its workspace (workel — Acme) rather than as identical entries you can't tell apart.

One thing to watch: re-authorizing an existing connection moves it, it does not add. Going through consent again on a connector you already added replaces its credential and disables the old one, so that connection switches to whichever workspace you pick. If you want both, add a new connector instead of re-authorizing the one you have.

Related MCP server: Google Workspace MCP Server

Running it yourself

This package is for the cases the hosted server doesn't cover: Claude Code, CI agents, the OpenAI Agents SDK — anywhere you want to run the process yourself and hold the credential. Everything below is about that.

It handles multiple workspaces differently, and better for this use case: set WORKEL_API_KEYS to a comma-separated list, one key per workspace, and every tool gains a workspace argument naming which one to act in. Ten tools stay ten tools however many workspaces you configure, rather than multiplying per workspace — which matters because every tool definition is context the model pays for on each turn.

Mint a dedicated read-only key before you start

Before pointing any AI client at this server, go to Workel → Settings → Developers and mint a new API key just for this purpose — don't reuse a key another integration already holds. Minting a key requires an owner or admin role. Grant it only the read:* scopes the tools in this release actually use (read:projects, read:tasks, read:members, read:events — see Tools below); leave every write:* scope unchecked unless you have deliberately decided to let an agent create and edit things in your workspace on its own. Use one key per machine or agent, name it so you remember what it's for later, and if a machine is retired or a client is compromised, revoke that one key in Settings → Developers rather than rotating a key several tools share — revocation is instant and takes effect on the next request.

Two things worth understanding before touching the flags described below:

• WORKEL_ENABLE_WRITES is a local operator consent flag, not an authorization boundary. It can only ever narrow what an already-scoped key is offered, never widen it — and because it lives in a config file or environment variable that an AI coding agent typically has write access to, an agent running on your machine can flip it back to true itself. A local flag is not something an untrusted agent can be trusted to leave alone. The key's own scopes — granted deliberately at mint time, and revocable at any time — are the real gate.

• A WORKEL_API_BASE_URL override sends your key to another host. Every request this server makes carries your key in the Authorization header. If WORKEL_API_BASE_URL ever points at a URL you don't control, that host receives your key on every call. This client refuses a plain http:// override except to localhost/127.0.0.1/[::1] for exactly this reason. The same logic applies to a real key pasted into any file: if it's ever committed to git, rotating the key is the only real fix — git history is forever. A later commit that deletes the line does not remove it from the repository's history, and anyone who cloned the repo in between still has the old key.

Install

npx -y @workel/mcp@0.4.0

Pin the version — 0.4.0 above is this package's current release; check npm view @workel/mcp version for the latest one before you pin it. The unpinned form below is convenience only, fine for a one-off manual try, not for anything an agent's config runs unattended:

npx -y @workel/mcp

Environment variables

doctor

Run npx -y @workel/mcp@0.4.0 doctor any time your MCP client reports only "server failed to start" with no further detail. It runs the exact same startup check the server itself runs — load config, then probe GET /me — and prints a plain-text report to stdout instead of trying to speak the MCP protocol:

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

doctor never starts a transport and never talks to your MCP client — it's a standalone command you run from a terminal, and it exits 0 on success or 1 on any failure (missing/invalid WORKEL_API_KEY, an unreachable API, or a key the API rejects). Unlike the one-line summary the server prints to stderr on a normal boot (which omits the base URL when it's the default), doctor always prints the effective base URL — including when it's the default — because a doctor run is exactly the moment a tampered WORKEL_API_BASE_URL needs to be visible.

Tools

This release registers the following read tools. workel_whoami needs no scope at all and works with any valid key; every other tool is only registered when the key's scopes (discovered via the GET /me probe above) include the scope listed. List tools return 25 results per call by default (50 max — this client caps below the API's own 100 deliberately, see src/tools/conventions.ts) and page via an opaque cursor / next_cursor pair.

Write tools

Four, and they register only when both gates pass: the key carries the matching write:* scope and WORKEL_ENABLE_WRITES=true is set. Either one alone registers nothing, so a read-only install never sees them.

No tool deletes anything. workel_update_task is annotated destructiveHint: true, so a client that honours annotations prompts before each call; the read tools are annotated read-only and run without one.

The hosted server at mcp.workel.com runs with writes enabled, so all thirteen tools are available there.

Limitations

replayed does not prove uniqueness. Every write this server's tools would make carries an Idempotency-Key, and the Workel API's idempotency store (24-hour retention, scoped to the calling key) replays the exact same response for a repeated attempt with the same key and the same request body — the second attempt reports replayed: true, and nothing is created or changed a second time.

replayed: false means this particular attempt genuinely executed — it does not mean no duplicate exists anywhere else. In particular: an error response is never cached, so retrying after a failure always re-executes for real; the idempotency record expires after 24 hours, so a very late retry re-executes for real; and the store is namespaced per API key, so the same literal Idempotency-Key value sent under a different key never collides with — and never protects against a duplicate created by — the first one. Unless a tool call explicitly reuses the same idempotency key across two attempts, each attempt is a genuinely independent write as far as the server can tell.