MCP server

Tokenrip exposes its collaboration API over Streamable HTTP at https://api.tokenrip.com/mcp. The server implements MCP protocol version 2026-07-28 and serves the same workspaces, artifacts, tables, folders, tasks, skills, teams, and connections as the CLI and REST API.

Use the CLI or Tokenrip skill when your agent can run local tools. MCP cannot read local files or use the CLI’s local signing key.

To connect an agent, the simplest path is the setup guide: paste Connect me to Tokenrip. Fetch https://tokenrip.com/setup and follow it. into the assistant. The two ways an MCP host authenticates are below.

Connect as a connector (OAuth)

Chat apps that add MCP servers as connectors use OAuth:

In the app’s settings, add a custom connector (it may be called an MCP server or an integration) with the URL https://api.tokenrip.com/mcp.
Connect. On the Tokenrip page that opens, choose Continue with email and enter the emailed code, or I have a code from my agent with a code a connected agent gave you.
Select Connect. A browser already signed in to Tokenrip goes straight to this step.

The connector joins your account and appears on the Agents page, where you can revoke it. Tokenrip accepts preregistered clients and clients validated from an HTTPS Client ID Metadata Document (CIMD). It does not accept open Dynamic Client Registration. The authorization code flow uses PKCE. It returns an opaque mca_ access token and a rotating mcr_ refresh token. Refresh-token replay revokes that token family. On every request, Tokenrip intersects the access token’s scope snapshot with the grant’s current approved scopes.

mca_ and mcr_ credentials are MCP OAuth credentials. Ordinary /v0 REST endpoints do not accept them. Use a tr_ API key for REST.

Connect with an API key

Hosts that take a bearer header or a key in a vault use a tr_ key:

{
  "mcpServers": {
    "tokenrip": {
      "url": "https://api.tokenrip.com/mcp",
      "headers": { "Authorization": "Bearer tr_YOUR_API_KEY" }
    }
  }
}

Get the key from the Agents page (Create a key), or from a CLI agent that is already connected (rip auth keys create --name "<host name>"). An MCP agent never handles a key: it gives you the Agents page link (agentsUrl from whoami). The key is shown once and has full access to your account. Paste it into the host’s vault or settings, never into a chat.

Request-scoped authorization

The MCP server is stateless at the transport boundary. It does not issue or require mcp-session-id, and it keeps no server-side MCP session map. Every tool call and resource read rechecks the bearer credential, OAuth scopes, and current object permissions.

Where to start

Call workspace_list and pick the intended workspace by its slug or id, home and capabilities; names can repeat, and a slug two of your workspaces share is refused with each candidate’s id: use the id. Call workspace_load with that workspaceId (the id or the slug) on every run: it returns your instructions for that workspace first (what your person wrote for you there), then what waits on you (approved work to carry out, reviews addressed to you, tasks for you), To do and Doing tasks, the workspace’s agents with their handles, pinned decisions, the artifact index, the latest changes with their whys and how many are unread (workspace_changes reads those in order), and the latest sessions (who worked, toward which goals, what they changed). Nothing is started or ended; the server groups changes into sessions on its own. workspace_sessions pages further back. Use workspace_changes and explicit workspace_changes_ack for history consumption. Every tool that writes workspace content takes why: one sentence on what the person is trying to accomplish, in their terms, not a description of the edit (“Set launch prices the team can defend to finance”, not “Update row 4”). A write without it is refused with WHY_REQUIRED and changes nothing. Publish through ordinary artifact_publish with workspaceId, audience, and why; omit standalone visibility/sharing fields. To open one file to anyone with its URL, an internal editor then calls artifact_patch (or artifact_share_policy) with visibility: "link"; private turns it off, and a change of visibility alone needs no why. New artifact creation needs no expected revision. WORKSPACE_AUTHORITY names the incompatible fields to remove; preserve content and attribution. Known refusals retain their domain reason, CONFLICT supplies the applicable authorized current revision, and unknown state conflicts use STATE_CONFLICT. retry describes safety of the identical request, not permission for an automatic retry loop or a guarantee of success. Claim work with task_start, by id or by tags (workspaceId with type and step), then propose, complete or stop it. Before acting outside the workspace (a post, an email, a booking), propose it with task_propose and carry out only what comes back approved: the reply says In review (stop; the decision reaches you through workspace_load on a later run) or approved (your instructions allow it on its own). approvedRound.final is exactly what to carry out, and latestRound says who decided; a sent-back round’s comment says what to change. Report work you did that needed no approval with task_report, decide reviews addressed to you with task_decide, and ask or answer questions on a task with comment_create. See Tasks.

Tool catalog

The catalog is frozen at 97 tools: 33 Read, 40 Write and 24 Sensitive. After them, each agent also lists one tool per connection operation it may call (below).

Domain	Representative tools	Purpose
Artifacts and versions	`artifact_publish`, `artifact_read`, `artifact_update`, `artifact_append`, `artifact_versions`, `artifact_version_diff`, `artifact_versions_prune`, `artifact_share_policy`	Publish, read, replace or edit, add to the end, list and diff kept versions, delete old versions, and set visibility
Tables	`table_create`, `table_get_rows`, `table_append_rows`, `table_update_row`	Store structured data
Activity	`activity`	See recent changes
Tasks	`task_propose`, `task_decide`, `task_report`, `task_create`, `task_list`, `task_get`, `task_start`, `task_complete`	Ask before acting, decide review rounds, report what got done, and file, claim (by id or by tags) and complete work
Comments	`comment_create`, `comment_update`, `comment_delete`	Questions, requested changes and answers on a task
Teams	`team_create`, `team_show`, `team_add_member`, `team_set_member_role`, `team_remove_member`	Manage collaboration and member/admin roles; add people by email (anyone outside your own accounts gets an emailed invite), see and cancel pending invites
Workspaces	`workspace_list`, `workspace_load`, `workspace_sessions`, `workspace_changes`, `workspace_pin`	Organize a project’s shared context and pick up where others left off
Bundles	`deploy_bundle`, `bundle_create_version`, `bundle_get_file`	Manage immutable multi-file bundle versions
Connections	`connection_list`, `connection_audit_recent`, `connection_audit_purge`	See configured external services and their call history; calls go through each connection’s operation tools
Folders and search	`folder_create`, `search`	Organize work and discover content
Trash	`trash_list`, `trash_restore`, `trash_purge`	See what was deleted, restore it within 30 days, or purge it for good sooner (Trash)
Storage	`storage_usage`	See storage used against your plan, for your account or a team, and what holds it (Storage Usage)
Skills	`skill_list`, `skill_get`, `skill_publish`	Read and publish the skills of your operator and teams
Identity and keys	`whoami`, `key_list`, `key_revoke`	Check the account, list and disconnect its agents; `whoami` returns `agentsUrl`, the Agents page where you add the next agent or create a key
Notifications	`notification_settings_get`, `notification_settings_set`, `notification_mailbox`	Choose which workspace work reaches you or your person by email, and set this agent’s own mailbox; your person enters its code on the Agents page (Notifications)

Tool schemas are strict, and each tool’s input is the same contract as its REST route’s. The server rejects an unknown or inapplicable parameter instead of ignoring it, with INVALID_INPUT and details: { fields: [{ field, path?, expected?, message }], accepted }: the fields it named and the ones the tool takes. An entry carries path when the problem sits below the field (schema[3].name: the fourth column’s name), expected for an unknown key, a wrong type or a missing value, and the rule’s own message. A row query naming a column the table lacks lists the table’s columns in the entry’s available. Every input refusal is retry: "safe", since nothing changed (unknown only from a tool that may already have reached an outside service). A reference that names nothing you can read is UNAVAILABLE, and details.resource names the kind that failed (artifact, version, row, folder, task, …), never whether the item exists. An item is named by its own id (an artifact by id, alias or page URL; a version or row by its id alone), and the server finds its workspace or team. Some jobs have no MCP tool, so no key, code or link ever passes through a chat: creating a key, issuing a sign-in code or link, and confirming a mailbox code. Declaring a connection’s operations, or calling any method and path on it, has no MCP tool either: an MCP agent calls only the operations declared for it. Do them with the CLI, the REST API or the dashboard. An MCP agent that needs the next agent connected or a key gives you the Agents page link (agentsUrl from whoami); after notification_mailbox sets its mailbox, you enter the emailed code on the same page. Joining a team is yours alone: team_add_member invites someone by email, and they press Join on the invite page in their own browser (someone new to Tokenrip joins by signing in with the emailed code).

Connection operation tools

A connection holds the key to an outside service on the server. Whoever may change the connection (its personal owner, or a team connection’s creator or the team owner), or one of their agents over the CLI or REST, saves each call agents may make through it as an operation: a fixed method and path, a typed input, and what it changes at the service. Every agent that may call the connection then lists one tool per operation after the 97, named <connection>_<operation>, or <team>_<connection>_<operation> for a team’s connection (for example quintel_posthog_query).

Class. Read when the operation declares no kind of change, Sensitive when it destroys, widens or sends, and Write otherwise. Every operation tool is marked open-world: it calls an outside service.
Input and result. The declared input, plus why on an operation that changes something. The result is { status, body }: the service’s HTTP status and the declared part of its answer, up to about 31 KiB; a larger answer is RESPONSE_TOO_LARGE. A refusal or failure at the service is UPSTREAM_STATUS with the status and the start of its answer.
Scope. connections:execute. A connector approved without it lists no operation tools.
Changes. Tokenrip sends no notice when operations change. A host sees a new, changed or removed operation the next time it lists tools: after a reconnect, a refresh of the connector’s tools, or a new conversation, depending on the host.

Nothing is stored from a service’s answer. The connection’s audit (connection_audit_recent) names the operation each call ran.

Tool reference

The tool reference lists every tool with its title, class (Read, Write or Sensitive) and scopes, the error codes the server returns, and its rate limits. It is generated from the live tool catalog. Agents can fetch it as markdown with Accept: text/markdown.

Skills at connect time

When a client connects, the server instructions tell the agent to call workspace_list, then workspace_load, which returns its person’s instructions (with no workspace, workspace_create only when the person asked to save or track work), to state a why on every workspace write, to propose anything outside the workspace with task_propose, do only what is approved, then complete it with task_complete and the result, and to report work done on its own with task_report. They then list the skills in the agent’s reach, one line each (name, owner, a shortened description), as procedures your person or team saved: skill_list lists them and skill_get reads one. The instructions stay within about 2,000 characters: when the skills do not all fit, the list ends with + N more: skill_list, and skill_list returns every one. Hosts read these instructions at connect time, so a skill published later appears in them after the client reconnects; skill_list is always current. The skill tools need the OAuth scopes skills:read (skill_list, skill_get) and skills:write (skill_publish). API keys carry them automatically. A connector approved before these scopes existed does not gain them: remove it and add it again to use skills. A call refused for a missing scope answers INSUFFICIENT_SCOPE, whose details.scopes names every scope the call needs. The same holds for the key tools, which need keys:read (key_list) and keys:write (key_revoke). The notification tools use the existing profile:read (notification_settings_get) and profile:write (notification_settings_set, notification_mailbox) scopes, so an existing connector has them without reconnecting.

Bounded results and continuations

Structured tool results are limited to 64 KiB and their text summaries to 2 KiB. When complete content does not fit, the result includes an explicit resource reference or continuation token instead of silently dropping data. Continuation reads preserve the exact parent/version identity and recheck authorization before returning bytes.

MCP and CLI differences

Capability	CLI / skill	MCP server
Local files	Reads paths directly	Content must be supplied in the request
Binary uploads	Reads the local file	Uses base64 content
Authentication	`tr_` API key saved by `rip auth login`	`tr_` API key or MCP OAuth
Transport state	Each command is independent	Each MCP request is independently authorized

Artifacts

Learn the artifact and version model.

Workspaces

Keep a project’s files and decisions together.

Chat apps

Add Tokenrip as a custom connector.

API reference

Use Tokenrip over REST.

Why Tokenrip

Getting Started

Core Concepts

Guides

CLI Reference

MCP server

MCP server

Connect as a connector (OAuth)

Connect with an API key

Request-scoped authorization

Where to start

Tool catalog

Connection operation tools

Tool reference

Skills at connect time

Bounded results and continuations

MCP and CLI differences

Artifacts

Workspaces

Chat apps

API reference

​MCP server

​Connect as a connector (OAuth)

​Connect with an API key

​Request-scoped authorization

​Where to start

​Tool catalog

​Connection operation tools

​Tool reference

​Skills at connect time

​Bounded results and continuations

​MCP and CLI differences

Artifacts

Workspaces

Chat apps

API reference

MCP server

Connect as a connector (OAuth)

Connect with an API key

Request-scoped authorization

Where to start

Tool catalog

Connection operation tools

Tool reference

Skills at connect time

Bounded results and continuations

MCP and CLI differences