MCP client setup

The server turns each REST API operation into a tool. A tool call uses the same scopes, rate limits, input validation and idempotency rules as its REST operation.

The MCP setup page has client configurations, a permission-filtered tool list and a connection test.

Add WorkRoad to a coding toolCopy Anchor Link

Claude Code, Codex, Cursor and VS Code connect without an API key too: add the address, then sign in to WorkRoad when the tool asks.

• Claude Code. Run claude mcp add --transport http workroad --scope user https://workroad.app/api/mcp, then run /mcp in Claude Code to sign in.
• Codex. Run codex mcp add workroad --url https://workroad.app/api/mcp. Codex opens WorkRoad for you to sign in. codex mcp login workroad signs in again later.
• Cursor. Add "workroad": { "url": "https://workroad.app/api/mcp" } under mcpServers in ~/.cursor/mcp.json, then sign in to WorkRoad when Cursor asks.
• VS Code. Run code --add-mcp '{"name":"workroad","type":"http","url":"https://workroad.app/api/mcp"}'. VS Code asks you to sign in when it starts the server.

To give an agent a fixed key instead, see Connect a client with an API key.

Connect a client with an API keyCopy Anchor Link

Clients that support OAuth, such as Claude Code, can connect the way ChatGPT and Claude do: add the URL and sign in when asked. To give an agent a fixed key instead, create an API key in Settings → Developers → API keys. The Full access template gives the agent every tool: it can create subjects, timetables, tasks, notes and sets, practise flashcards, take tests and run AI features. Pick a narrower template or tick scopes yourself to limit it. Put the key in an environment variable once, for example in your shell profile, so no config file holds the key itself:

export WORKROAD_API_KEY=wr_live_...

Claude Code. Add this to .mcp.json in your project. Claude Code expands ${WORKROAD_API_KEY} from its environment when it uses the server:

{
   "mcpServers": {
      "workroad": {
         "type": "http",
         "url": "https://workroad.app/api/mcp",
         "headers": { "Authorization": "Bearer ${WORKROAD_API_KEY}" }
      }
   }
}

Or register it from the command line. claude mcp add-json takes the server object itself, without the mcpServers wrapper. Keep the single quotes so your shell leaves ${WORKROAD_API_KEY} alone: Claude Code then stores the reference and resolves it when it connects, so the key is not written to its config.

claude mcp add-json workroad '{"type":"http","url":"https://workroad.app/api/mcp","headers":{"Authorization":"Bearer ${WORKROAD_API_KEY}"}}'

Codex. Run this, or add the table below to ~/.codex/config.toml. Codex reads the variable named in bearer_token_env_var and sends it as the bearer token:

codex mcp add workroad --url https://workroad.app/api/mcp --bearer-token-env-var WORKROAD_API_KEY

[mcp_servers.workroad]
url = "https://workroad.app/api/mcp"
bearer_token_env_var = "WORKROAD_API_KEY"

Cursor. Add this to .cursor/mcp.json in your project or ~/.cursor/mcp.json for every project. Cursor reads the variable from the environment it was started in, so launch it from a shell where the variable is set:

{
   "mcpServers": {
      "workroad": {
         "url": "https://workroad.app/api/mcp",
         "headers": { "Authorization": "Bearer ${env:WORKROAD_API_KEY}" }
      }
   }
}

Use a key with only the scopes the agent needs, and revoke it in Settings if it leaks.

In Claude Code, run /mcp to check the connection. workroad should show as connected, with its tools listed. A 401 means the key is missing, wrong or revoked, or the variable was not set when the client started.

Other MCP clients connect the same way: point them at /api/mcp and send the key as Authorization: Bearer <key>, or let them sign in with OAuth as described in the protocol reference.

Test modeCopy Anchor Link

https://workroad.app/api/test/mcp has the same tools, but each one returns the fixed example response from its operation page instead of running, as test mode does for REST. Register it under a second name, such as workroad-test, to try an agent without touching your data. In Claude Code:

claude mcp add-json workroad-test '{"type":"http","url":"https://workroad.app/api/test/mcp","headers":{"Authorization":"Bearer ${WORKROAD_API_KEY}"}}'

For Codex and Cursor, use the snippets above with the /api/test/mcp URL.

What your AI can changeCopy Anchor Link

With the matching scopes, an assistant can read and change:

• Profile: name, username, bio, status, location, and what your public profile shows.
• Language, time zone and privacy: the app language, your time zone (tasks keep their due date and time on the clock), and whether you appear on leaderboards.
• Notifications: quiet hours, the email digest, push content, calendar alarms, and each kind's bell, email and push switches and timing. It can turn email back on after a bounce.
• Review settings: new cards and reviews a day, desired retention, the daily goal, leeches and per-subject overrides.
• Task preferences and dashboard: task types, due-date colours, and which dashboard cards show, in what order and size.
• Calendar feeds: list and delete feeds. You create one yourself in Settings → Calendar feeds: an address keeps working after the assistant's access ends.
• Webhooks: list, pause, re-enable, test and delete them, only with an API key that has webhooks:manage. Connected apps never get it. You add a webhook or change its URL yourself, in Settings → Developers → Webhooks.
• Your subjects, timetables, tasks, notes and study sets.

The built-in Copilot changes the same settings through the same operations, after you confirm each change on its card.

It can't add a webhook or change where one sends, and it can't change your password, email address, two-factor, passkeys, sign-in methods or sessions, API keys or connected apps, plan or payment, or delete your account. Your theme and AI model choice live in your browser, and browser push, profile pictures and Google Calendar or university connections need you in the app.

Which tools appearCopy Anchor Link

The key's scopes decide the tool list. Each tool is named after its operation's id, such as listTasks or createNote, and appears only when the key's scopes allow that operation. A key with only tasks:view sees listTasks, getTask, listTaskTypes, listSubjects and getSubject, plus getMe, getAiAllowance, searchDocs and getDoc, which any key may call. Each operation page lists its required scopes; see keys and scopes.

The server builds the list when the client asks for it. After you change a key's scopes, reconnect (in Claude Code, /mcp) so the client fetches the new list.

Tool calls count against the key's REST rate limits: a read tool uses the read bucket and a write tool the write bucket.