# RedRover MCP developer guide

MCP version 0.1.0 · October 5, 2026

Connect an agent to your workspaces, requirements, tasks, releases and personal time. RedRover is the server; no second daemon, database or desktop installation is needed. This guide describes the implemented contract. Ask your RedRover administrator whether MCP is installed in your environment; the public addresses below do not imply those servers have been updated.

## Important: Codex mode is required for this Bearer-key setup

**If you are using the Codex app, select Codex mode before connecting to RedRover.** RedRover's personal MCP key uses Bearer authentication in Codex mode.

**ChatGPT mode requires OAuth. RedRover does not currently support MCP OAuth, so this connection does not work in ChatGPT mode or ChatGPT.** Creating a RedRover key or adding it to `config.toml` does not enable ChatGPT access. Switch to Codex mode and start a Codex conversation to use this setup.

This is about the conversation mode, not how you sign into Codex: signing into Codex with your ChatGPT account is fine. Claude Code and terminal clients can also use the key-based instructions below.

## 1. Enable access and create a connection

1. Sign into the environment you want to use.
2. A workspace owner or account administrator opens Workspace Settings → MCP access and enables the workspace. Choose maximum access for Tasks, Requirements, Releases, Milestones, Time and Plans.
3. Open your profile menu → My MCP connections (`/mcp-access`). Choose New connection, give it a name, and select enabled workspaces, expiry, timezone and resource permissions. If no workspace is enabled, the page explains the next step; owners and administrators can open workspace configuration directly from that prompt. Save the workspace's access, then choose New connection again. A single enabled workspace is selected for you.
4. Copy the key once and store it securely. Each person should use their own connection. The agent acts as that person; membership and permissions are checked again on every call.
5. Copy the endpoint from the connection page. Do not append a key to the URL.

The key appears in **Save your connection key** immediately after creation. Use **Copy key** before closing that dialog. If you lose it, choose **Rotate key** beside your connection; the previous key stops working. Workspaces start with MCP off, so an empty selection does not mean a key is missing from application secrets.

| Environment | MCP endpoint |
| --- | --- |
| Local | `http://localhost:8080/redrover/mcp` |
| Development | `https://redrover.hatchery.com/mcp` |
| Production | `https://www.askredrover.com/mcp` |

The connection page uses the application's configured URL (`h.url()`). Localhost is reachable only from that computer. Use HTTPS for shared servers. Keys and workspace IDs belong to the environment where they were created.

Access is the intersection of the connection's grants, the owner's workspace limits, and your current RedRover permissions. Disabled workspace features remain unavailable for changes. Delete access is off by default. Linked tasks require read access to their parent requirements/releases too. Archived workspaces, revoked memberships and expired/revoked keys lose access. A connection never crosses its account boundary.

Start with read-only access and enable changes you intend the agent to make. Key settings cannot give you permissions you do not already have. The first release excludes financial values, Task Orders, approvals, signatures, users, account administration, files, Knowledge Base and legal contracts. Maggie's in-app capabilities are separate from these MCP tools.

## 2. Set the key in your client environment

Use `REDROVER_MCP_KEY` for the personal key. Do not commit it or paste it into an agent conversation. In macOS/Linux zsh:

```sh
read -rs 'REDROVER_MCP_KEY?RedRover MCP key: '
export REDROVER_MCP_KEY
```

In bash:

```sh
read -r -s -p 'RedRover MCP key: ' REDROVER_MCP_KEY
export REDROVER_MCP_KEY
```

In Windows PowerShell:

```powershell
$rrMcpSecret = Read-Host 'RedRover MCP key' -AsSecureString
$rrMcpCredential = [System.Net.NetworkCredential]::new('', $rrMcpSecret)
$env:REDROVER_MCP_KEY = $rrMcpCredential.Password
Remove-Variable rrMcpSecret, rrMcpCredential
```

Start the client from this same terminal. A GUI app opened from the Dock may not inherit terminal variables; supply the variable through that client's supported environment mechanism, then restart it. Do not replace your existing client configuration: merge the RedRover server entry.

## 3. Codex

**Select Codex mode in the app. Do not use ChatGPT mode for this configuration.** ChatGPT needs an OAuth connection, which RedRover does not currently provide.

Add the entry to `~/.codex/config.toml` (or the trusted project's `.codex/config.toml`), choosing your environment's endpoint:

```toml
[mcp_servers.redrover]
url = "http://localhost:8080/redrover/mcp"
bearer_token_env_var = "REDROVER_MCP_KEY"
```

Launch Codex with the variable available, restart the MCP connection, and check its server list. Open a new conversation in **Codex mode**, then ask: “Use RedRover rr_context to show my connected workspaces. Do not change anything.” This endpoint uses a key, so `codex mcp login` is not a RedRover sign-in flow.

Configuration reference: [official Codex MCP documentation](https://developers.openai.com/codex/mcp).

## 4. Claude Code

Merge this server into the project's `.mcp.json`. The `${REDROVER_MCP_KEY}` reference is intentional; keep the actual key outside the file:

```json
{
  "mcpServers": {
    "redrover": {
      "type": "http",
      "url": "http://localhost:8080/redrover/mcp",
      "headers": {
        "Authorization": "Bearer ${REDROVER_MCP_KEY}"
      }
    }
  }
}
```

Launch Claude Code from the terminal containing the exported variable. Approve the project server when prompted, then use `/mcp` to check the connection. Ask it to call `rr_context` before writing anything. This guide targets Claude Code. Claude.ai and clients that require browser OAuth are not supported by this key-only release; do not assume they accept this configuration.

Configuration reference: [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

## 5. Terminal clients and curl

Transport: stateless Streamable HTTP. Send JSON-RPC POST requests with `Content-Type: application/json`, `Accept: application/json, text/event-stream`, and exactly one `Authorization: Bearer …` header (or `X-API-Key`). Authentication is not a cookie/login session. No `Mcp-Session-Id` is required. A GET or browser visit is not a connection test; this endpoint returns 405 for GET.

Set the environment URL. For curl, keep the key out of its command-line arguments by using stdin configuration. The helper below works in bash/zsh, requires curl, and does not follow redirects:

```sh
export REDROVER_MCP_URL='http://localhost:8080/redrover/mcp'
rr_mcp() {
  test -n "$REDROVER_MCP_KEY" || return 1
  printf 'header = "Authorization: Bearer %s"\n' "$REDROVER_MCP_KEY" |
    curl --config - --silent --show-error --fail-with-body \
      --request POST "$REDROVER_MCP_URL" \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json, text/event-stream' \
      --data-binary "$1"
}
```

Initialize, then notify initialization:

```sh
rr_mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"redrover-terminal","version":"1.0"}}}'
rr_mcp '{"jsonrpc":"2.0","method":"notifications/initialized"}'
```

Use the returned protocol version for any `MCP-Protocol-Version` header your client sends. List the tools and read connected workspaces:

```sh
rr_mcp '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
rr_mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rr_context","arguments":{}}}'
```

The catalog describes the tools; a listed tool does not grant permission to use it. Check `rr_context` for key grants and workspace limits. A tool failure can be an HTTP 200 response with `result.isError: true`; scripts must inspect it, not just curl's exit code. Successful initialization notifications normally have no response body. An HTTP client must accept the returned JSON or SSE content type.

## 6. Tools and common workflows

| Tool | Purpose |
| --- | --- |
| `rr_context` | Acting user, allowed workspaces, objectives, status/priority options, eligible member IDs and access limits |
| `rr_find_work` | Filter open/closed work by workspace, type, assignee, search, status, priority, parent requirement/release or dates |
| `rr_get_item` | Current item/version, its notes and visible tasks belonging to a requirement |
| `rr_create_items` | Atomic batch of 1–100 tasks, requirements, releases or milestones |
| `rr_update_item` | Version-checked changes to an item, including dates and requirement/release links |
| `rr_add_note` | Append progress without replacing the description |
| `rr_remove_item` | Archive through normal removal rules, requiring explicit delete access |
| `rr_my_time` | Your authorized recorded time, current timer and permitted scheduled blocks |
| `rr_time` | Start, stop, annotate or manually log your own time |
| `rr_plan_block` | Create, start or cancel your own scheduled work block |

Discover the current argument schemas with `tools/list`. Work references use numeric IDs; do not guess them. A requirement describes an outcome; its tasks describe the work. Create the requirement first, then use its returned ID in `fields.requirementId` when creating/linking tasks. Link a release using `fields.releaseId`. RICE fields include `reach`, `impact`, `confidence` (0–100), `effort` and `reachPeriod` (for example `2026-Q4`; use `YYYY-Q1` through `YYYY-Q4`).

Example agent requests:

- “Show my open tasks due today, grouped by workspace, and identify blockers.”
- “Show tasks due next week. First propose a realistic schedule; ask before creating blocks.”
- “Create these requirements, then add their tasks and link them to the release. Use the workspace's configured statuses.”
- “Start my timer on this task. Append a note when I finish and stop the clock.”
- “Review my actual time this week alongside planned blocks. Keep estimates separate from recorded hours.”

`rr_find_work` defaults to open work assigned to you. Use `assignee: "all"` when intentionally inspecting other eligible work, and `status: "all"` for closed work. `dueWindow` accepts `today`, `next7Days` (today plus six days), `nextWeek` (next Monday–Sunday), `overdue` and `all`. Dates are interpreted in the connection's IANA timezone; the response states the actual date window. With `hasMore: true`, repeat using `nextAfterId` as `afterId`.

Every write needs a new UUID `requestId`. Retry an uncertain response using the exact same ID and arguments; a committed change is replayed without duplication after current access is checked. Removed items, revoked access and archived workspaces can fail that check; replay never restores access. Reusing the ID for a different payload returns a conflict. Item edits/removal require the current `version` from `rr_get_item`; on conflict, reread and reconcile before issuing a new write. Do not overwrite another person's work.

API dates use `YYYY-MM-DD`; scheduled `startLocal`/`endLocal` use `YYYY-MM-DDTHH:mm` with an IANA timezone. RedRover's UI displays dates as mm/dd/yyyy. `rr_time` stop/annotate/corrections require the entry ID and revision from `rr_my_time`; corrections also need a reason. Plans do not record hours. `autoStart`/`autoStop` are off unless explicitly chosen; reminders are independent flags. Manual durations are whole minutes (1–1440 per entry). `rr_my_time` honors day/week/month or explicit from/to dates; recorded-time day allocation follows RedRover’s UTC accounting and plan blocks use the connection timezone. Only one personal timer can run, and a new start never silently switches it. Server reminders continue without an agent session.

## 7. Plain developer notes

Enable “Use plain developer language for agent notes” in connection preferences if desired. Maggie rewrites progress annotations concisely, with instructions to preserve facts, uncertainty, blockers and next steps. Technical/quoted excerpts bypass rewriting. This option affects note annotations, not requirement descriptions or acceptance criteria. Original submissions and saved notes are retained for provenance. If rewriting fails validation or Maggie is unavailable, that write is rejected; retry with original language by turning the option off. Review important notes rather than assuming any AI rewrite is infallible.

## 8. Rotation, errors and troubleshooting

Use **Access** under My MCP connections to change selected workspaces and resource permissions without replacing the key. New connections begin read-only; owner limits and current permissions still apply. Workspace owners can expand **Connections** on their workspace card and disconnect an individual agent.

Rotate or revoke under My MCP connections. Rotation immediately invalidates the previous key; replace the environment variable and restart the client connection. Lost keys cannot be displayed again. Removing workspace access or disabling MCP blocks that workspace immediately. Activity records tool, connection, outcome and elapsed time; credentials and note bodies are not shown in the activity table.

| Symptom | Check |
| --- | --- |
| Configured in Codex, but unavailable in ChatGPT mode | Switch to **Codex mode** and open a Codex conversation. RedRover's Bearer key does not enable ChatGPT access; ChatGPT requires MCP OAuth, which RedRover does not currently support. |
| 401 | Wrong environment, missing variable, expired/revoked key, or a REST API key used as an MCP connection |
| 403 / `forbidden` | Workspace enabled and selected, current membership, key grants, owner limits, parent read access and ordinary permissions |
| 404 or HTML | Deployment includes the servlet and dependencies; URL ends with `/mcp`, not `/vip` or `/mcp-access` |
| GET 405 | Expected; initialize using POST |
| 400 / `invalid_request` | Argument names/types, required UUID, date order and workspace options |
| `conflict` | Reread the item/version, or use a new request ID for a different operation |
| 429 | Wait for `Retry-After` before retrying |
| 503 / `unavailable` | Operator checks migration, database, dependencies and safe server logs; retry uncertain writes with the same request ID |
| `rewrite_unavailable` | Turn off plain-language notes or have an administrator check Maggie configuration |
| Desktop client cannot see key | Ensure its process actually received the environment variable and restart the connection |

Keep keys in a credential manager or protected runtime environment. Share configuration templates, not keys. Use a separate connection per person/client so it can be revoked independently. Unset temporary keys when finished: `unset REDROVER_MCP_KEY` in bash/zsh, or `Remove-Item Env:REDROVER_MCP_KEY` in PowerShell.

For a terminal service or scheduled integration, use a dedicated non-administrator RedRover identity with the intended workspace membership. Create a narrowly scoped connection for that identity and inject `REDROVER_MCP_KEY` through the service’s protected environment or credential manager. Restart the client when rotating it, honor expiry and Retry-After, and inspect tool-level errors. A service key acts as that identity and can record only its own time. Never use a human administrator’s broad key for an unattended worker.

## Personal notes (October 7, 2026)

Open the notebook icon in the app's top-right header, then choose **MCP access**. Personal note access is off until the note owner enables Read, Add, Edit and/or Delete for a specific active connection. This is independent of workspace permissions. Administrators and workspace owners cannot grant access to another person's notes. Locked and encrypted notes remain inaccessible to MCP. `rr_context` reports `personalNotesEnabled`.

| Tool | Purpose | Required arguments |
| --- | --- | --- |
| `rr_personal_notes_list` | Own note summaries and folders | None |
| `rr_personal_notes_get` | Own unprotected note HTML, current revision, attachment names | id |
| `rr_personal_notes_create` | Add note; first text line defines title | requestId, html; optional folderId |
| `rr_personal_notes_update` | Replace note HTML and folder | requestId, id, revision, html, folderId (0 = unfiled) |
| `rr_personal_notes_delete` | Delete unprotected note and attachments | requestId, id, revision |

Use safe Redactor HTML such as `<p>My title</p><p>My note</p>`. Read the current note before editing/deleting and keep a stable requestId UUID for retries. A revision conflict requires rereading. Personal writes return an id/revision receipt; get the current note to read its content. Receipts retain no text or title. Replays recheck current access/protection. These tools do not rewrite content with AI, send workspace notifications, upload files, or unlock notes. `rr_add_note` continues to mean a work-item discussion, not a personal note.