# Coding tools and other clients

> Connect coding tools and other MCP clients with OAuth or an API key.

Source: https://workroad.app/docs/mcp-clients

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](https://workroad.app/user/developers/mcp) has client configurations, a permission-filtered tool list and a connection test.

## Add WorkRoad to a coding tool

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-key).

## Connect a client with an API key

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 → AI apps & API → 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:

```bash
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:

```json
{
   "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.

```bash
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:

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

```toml
[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:

```json
{
   "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](https://workroad.app/docs/mcp-reference#authentication-and-protocol-errors).

## Test mode

`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](https://workroad.app/docs/api/conventions#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:

```bash
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 change

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 → AI apps & API → 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 appear

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](https://workroad.app/docs/api/conventions#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](https://workroad.app/docs/api/limits#rate-limits): a read tool uses the read bucket and a write tool the write bucket.