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.
Authentication: a bearer token on every request. There is no OAuth flow.

Create a token

Open Settings › API tokens and choose Create token.
Give it a name, for example Claude Code on my laptop.
Choose its scopes.
Choose when it expires: Never, In 30 days, In 90 days, or In a year.
Choose Create token.

The token starts with rvp_. It is shown once and stored hashed, so copy it immediately. Only you can see the tokens you create. Revoke a token from the same list; it stops working immediately.

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

Scopes

Scope	Label	Grants
`tasks:read`	Read tasks	List repositories, workers, and tasks; read task state, transcripts, changes, and files.
`tasks:write`	Run tasks	Create tasks and conversations, send messages, cancel, archive, and restore.
`git:write`	Git actions	Commit, push, open and merge pull requests, and discard changes.
`linear:read`	Read Linear	Search the organization’s Linear teams, projects, and issues, and link a task to an issue.
`linear:write`	Write to Linear	Create and update Linear issues, and comment on them.

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 exposes 29 tools. None take an organization argument: the token decides it. IDs are prefixed: repo_ for repositories, wt_ for tasks, ch_ for conversations.

Tasks

Tool	Scope	What it does
`rivets_whoami`	none	The account, organization, and token in use.
`rivets_list_repos`	`tasks:read`	Repositories connected to the organization.
`rivets_list_workers`	`tasks:read`	Workers and whether they are online.
`rivets_list_tasks`	`tasks:read`	Tasks, newest first.
`rivets_get_task`	`tasks:read`	One task’s branch, status, and conversations.
`rivets_get_task_output`	`tasks:read`	A condensed transcript, paged with a cursor.
`rivets_list_changes`	`tasks:read`	Changed files with line counts, optionally with diffs.
`rivets_read_file`	`tasks:read`	One file from a task’s checkout.
`rivets_create_task`	`tasks:write`	Start a task: worktree, branch, first conversation, and agent run in one call. Optionally linked to a Linear issue.
`rivets_create_chat`	`tasks:write`	Start another conversation in an existing task.
`rivets_send_message`	`tasks:write`	Steer a running agent, or resume a finished one.
`rivets_cancel_task`	`tasks:write`	Stop the running agent.
`rivets_archive_task`	`tasks:write`	Archive a finished task.
`rivets_restore_task`	`tasks:write`	Restore an archived task while the worker still has its checkout.

Git and pull requests

Tool	Scope	What it does
`rivets_pr_workspace`	`tasks:read`	The pull request draft, git state, GitHub checks and reviews.
`rivets_prepare_pr`	`git:write`	Capture what will be published, and optionally generate a title and description.
`rivets_save_pr_draft`	`git:write`	Save the Rivets draft. Does not update GitHub.
`rivets_run_pr_action`	`git:write`	Commit, push, create or sync the pull request, or continue or abort a merge. Safe to retry.
`rivets_update_pr`	`git:write`	Update the pull request’s title, body, base, or draft state on GitHub.
`rivets_merge_pull_request`	`git:write`	Merge the reviewed revision. Fails if new commits were pushed since.
`rivets_discard_changes`	`git:write`	Permanently discard uncommitted changes. Requires explicit confirmation.

Unlike people in the app, agents have no Merge anyway: rivets_merge_pull_request always requires the pull request to be ready to merge.

Linear

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

Tool	Scope	What it does
`rivets_linear_list_teams`	`linear:read`	Teams with their keys and workflow states.
`rivets_linear_list_projects`	`linear:read`	Find a project by name.
`rivets_linear_list_issues`	`linear:read`	Search issues. `assignee: "me"` resolves to your linked Linear account.
`rivets_linear_get_issue`	`linear:read`	One issue in full, with comments, attachments, and sub-issues.
`rivets_linear_create_issue`	`linear:write`	File a new issue.
`rivets_linear_update_issue`	`linear:write`	Change an issue’s title, description, state, assignee, priority, project, or labels.
`rivets_linear_create_comment`	`linear:write`	Comment on an issue as the Rivets app.

Assistant

rivets_watch_task and rivets_unwatch_task let the assistant be woken when a task finishes. They need the assistant scope, which only Rivets can grant to its own assistant sessions.

Rate limits

Limit	Applies to	When exceeded
120 calls per minute	Each token	HTTP `429` with `Retry-After`
20 task creations per hour	Each organization and creator	`rivets_create_task` returns a `rate_limited` error

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, insufficient_scope, not_found, rate_limited, and linear_not_connected.

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.