MCP server

Rivets is an MCP server. Anything you can do with tasks in the app, an agent can do over MCP: list repositories, start a task, read what the agent did, commit, open a pull request, and merge. Every call acts as you, in one organization, with your repository access.

Endpoint

https://app.rivets.dev/api/mcp

• Transport: Streamable HTTP, stateless. Send one JSON-RPC request per POST. There are no sessions.
• Protocol version: 2025-06-18. Clients that still speak 2025-03-26 are also accepted.
• Authentication: a bearer token on every request. There is no OAuth flow.

Create a token

1. Open Settings › API tokens and choose Create token.
2. Give it a name, for example Claude Code on my laptop.
3. Choose its scopes.
4. Choose when it expires: Never, In 30 days, In 90 days, or In a year. In the Mac and iOS apps, enter a number of days up to 365, or leave it empty for no expiry.
5. Choose Create token.

The token starts with rvp_. It is shown once and stored hashed, so copy it immediately. The list shows each token as Active or Expired, with when it was last used. Revoke a token from the same list; it stops working immediately and leaves the list.

Members see and revoke only their own tokens. Organization owners see every member’s tokens and can revoke any of them.

A token is bound to one user and one organization. It cannot reach any other organization.

Scopes

New tokens start with Read tasks and Run tasks selected. An agent only sees the tools its token’s scopes allow.

Connect a client

Claude Code

The token dialog prints this command, filled in with your token:

claude mcp add --transport http rivets https://app.rivets.dev/api/mcp --header "Authorization: Bearer rvp_..."

Codex

Put the token in an environment variable and point Codex at the endpoint:

export RIVETS_MCP_TOKEN=rvp_...
codex exec \
  -c mcp_servers.rivets.url="https://app.rivets.dev/api/mcp" \
  -c mcp_servers.rivets.bearer_token_env_var=RIVETS_MCP_TOKEN \
  -- "list my Rivets tasks"

This keeps the token out of the command line, where other users on the machine could see it.

MCP Inspector

npx @modelcontextprotocol/inspector

Choose Streamable HTTP, enter the endpoint URL, and add an Authorization: Bearer rvp_... header.

Other clients

Any client that speaks Streamable HTTP works. Send the bearer header on every request.

Tools

Rivets has 30 tools. Personal tokens can reach 28 of them; the other two are reserved for Rivets’ own use. None take an organization argument: the token decides it. IDs are prefixed: repo_ for repositories, wt_ for tasks, chat_ for conversations. A ? marks an optional argument.

Tasks

clientRequestId must be a new unique string for each real request. Sending the same one again returns the original task or conversation instead of creating a second one, so retries are safe.

Without provider, a new task runs on your agent defaults. Pass linearIssue: { id }, with an identifier such as ENG-123 or the issue’s ID, to link the task to a Linear issue. This needs the linear:read scope. The task shows the issue as its source, its Team discussion is connected to the issue, and the agent’s prompt starts with one line naming the issue. The issue’s description is not added, so put what the agent needs in your prompt.

Tasks that came from Linear can wait in awaiting_approval until a member approves them in Rivets. An agent cannot approve them or send them messages. See Linear.

Git and pull requests

Unlike people in the app, agents have no Merge anyway: rivets_merge_pull_request always requires passing checks and a fully published task.

Linear

These use your organization’s existing Linear connection. If Linear is not connected, they return an error saying so.

Issue IDs accept an identifier such as ENG-123 or Linear’s ID. List tools return nextCursor when there are more results; pass it back as cursor.

Reserved tools

rivets_watch_task and rivets_unwatch_task are used internally by Rivets to be woken when a task finishes. They need a scope that personal tokens cannot carry, so they never appear in your token’s tool list.

Rate limits

Errors

Authentication problems are HTTP errors: 401 for a missing, revoked, or expired token, 403 for a suspended account or removed membership. Tool failures, such as an offline worker or a missing scope, come back as tool results marked as errors, with a code and a readable message, so an agent can explain them and recover. Useful codes include worker_offline, worktree_archived, awaiting_approval, insufficient_scope, not_found, create_rate_limited, and linear_not_connected. A result over 60 KB comes back as result_too_large, asking the agent to narrow the request.

What MCP cannot do

MCP cannot manage API tokens, invite members, change organization settings, register workers, or open terminals. Those require signing in to Rivets. A leaked token can run and read tasks in one organization, but it cannot escalate beyond that.