# Derive [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/derive-to/derive  
**GitHub Stars:** 30  
**npm Downloads (last month):** 241  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/derive

## Description
Publish agent output to permanent versioned URLs, read review comments back, and revise.

## Tools
Capabilities this server exposes over MCP:

- **list_workspaces** — List every workspace signed in on this machine you can act in — id, name, your role, local description, and which is active. One login reaches them all; pass a workspace's id or name as the `workspace` argument to list_artifacts / read / catch_up / comment / publish to act there for that call.
- **list_artifacts** — List the artifacts in your workspace — short id, title, kind, current version, access, and browse `tags`. Defaults to this session's workspace; pass `workspace` (id or name from list_workspaces) to list another. Pass `tag` to list only artifacts carrying that tag (organize shows the vocabulary). Start here to find what to work on, then catch_up or read it.
- **search** — Find text within ONE artifact, or across a WORKSPACE — same tool, same behavior as the remote MCP server's `search`. Pass short_id to grep one artifact: matching lines with line numbers (and optional context), ripgrep-style, so you can then `read` a narrow `lines` range or `edit` that spot. Omit short_id to search across the workspace — the artifacts you can see, ranked by relevance and grouped by artifact — find WHICH doc has something before opening it. Searches the exact source by default (in:'text' searches the visible text instead). The query is matched literally (metacharacters are not special).
- **read** — Read an artifact's CONTENT by short id, as Markdown by default (HTML is converted). Omit `section` to see the outline first (heading slugs for a single-file doc, page paths for a bundle) — call again with a `section` (or "*" for the full document) once you know what you want. Pass `format:'html'` for the exact source (needed before publish `edits`), or a past `version` for history. Also accepts derive://guide, /connect, or /compatibility so the onboarding strings in server instructions work even when MCP resources do not. For what CHANGED or the comment threads, use catch_up instead.
- **catch_up** — START HERE on an artifact. Its state in one call: a summary, the review round, the versions since `since_version`, the open (and outdated) comment threads, and the full version history. Pass `comments` (open / addressed / resolved / outdated) to instead get that filtered thread list — your feedback queue. Pass `response_format='detailed'` (optionally with `since_version`/`to_version`) to fold in a line diff between two versions — of their readable Markdown form, not raw HTML. WAITING ON A REVIEW? Pass `wait` (seconds, max 50) to block until the human sends back — chain these instead of sleeping between polls.
- **comment** — Leave feedback, reply in a thread, react, and/or resolve or reopen a thread. Anchor a NEW comment to text with `quote`, or to a linked-bundle loop/graph part with `visual_target`. Reply by passing the thread id as `reply_to`.
- **organize** — Tags and collections in one tool — the library's findability layer.
• READ (no `short_ids`): the workspace's tag vocabulary (tag → count) and its collections. Call this before tagging to reuse an existing tag over a near-duplicate.
• READ (with `short_ids`): those artifacts' current tags + collections, plus `suggested` tags drawn from the most semantically-similar docs (when one id is given).
• WRITE: pass `add`/`remove`/`set` to change tags, `collection` to file artifacts, or `state:'archived'`/`'live'` to archive and restore. Each artifact is authorized on its own; ones you can't touch are skipped.
Tag freely and reuse the vocabulary — a well-tagged library is findable. Collections are heavier: a tag for plain findability, a collection when a set is a real unit.
- **publish** — Publish a single-file artifact and get a permanent URL, versions, and feedback (a chat-local artifact has none of these). OMIT short_id to create a NEW artifact (title recommended); PASS short_id to publish a new version (same URL). Provide the body as `content_path` (a local file this server reads and uploads — preferred, zero tokens) or `content` (inline text). To CHANGE PART of an existing artifact, prefer `edits` (exact-match search/replace against the stored source — read format:'html' first) over resending everything. Pass `addresses` with the thread ids this revision resolves. (Multi-page bundles are published via the web app or the remote /mcp server.) FULLY-STYLED HTML renders as-authored (own <style>/scripts/fonts) in the sandboxed viewer — declare your own <meta name="viewport"> to skip the mobile-reflow injection, and self-host binaries via POST /v1/assets (images and woff2 fonts) instead of inlining base64.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "derive": {
    "command": "npx",
    "args": ["-y","@derive-to/mcp"],
    "env": {
      "DERIVE_SERVER": "",
      "DERIVE_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `DERIVE_SERVER`, `DERIVE_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Derive MCP server does

The Derive MCP server gives compatible agents a way to publish work into the Derive artifact library. Supported content includes HTML pages, Markdown documents, LaTeX papers, presentations, and complete built sites. Each artifact receives a durable URL, while later publications become new versions under that same URL.

Agents can use Derive to retrieve comments and review feedback attached to an artifact, then produce a focused revision. Comments remain associated with the relevant work and can refer to specific text. Depending on the granted role, an agent can publish directly or suggest changes for a person to apply.

The workspace can keep artifacts private, share them with workspace members, or expose them publicly. Public links may also be protected with a password. Derive stores the content, version history, and comments together so another person or agent can continue from the artifact rather than reconstructing context from a conversation.

## How it works

The hosted MCP endpoint is available at `https://derive.to/mcp` and uses remote HTTP with OAuth. A compatible coding agent connects to that endpoint and acts with the role assigned by the workspace. Publishing access creates a retained, restorable version and notifies the workspace; lower access can limit the agent to proposing changes through comments.

Derive can also run as a local stdio MCP server. The repository provides the `@derive-to/mcp` npm package for this mode. The broader product can be hosted by Derive or self-hosted in one container. Self-hosting supports SQLite and local disk by default, with Postgres and S3/R2 available for larger deployments.

## Setup and configuration

For the hosted option, connect the agent to `https://derive.to/mcp`. Claude Code can be configured with `claude mcp add --transport http derive https://derive.to/mcp`; Codex can use `codex mcp add derive --url https://derive.to/mcp`. Cursor has a provided MCP installation link in the project documentation.

For local stdio operation, run `npx -y @derive-to/mcp`. Set `DERIVE_SERVER` to identify the Derive server, and use `DERIVE_TOKEN` when authentication should use a static bearer token.

A hosted account is not required for the anonymous draft flow. An uploaded draft can return a live URL and a claim link; claiming it turns the draft into a permanent, versioned artifact in a workspace. Authenticated workspace use provides the library, access controls, comments, and version history.

## Tools and capabilities

The Derive MCP server supports workflows built around these capabilities:

- Publish an artifact or a new version to a durable URL.
- Read comments and review feedback attached to published work.
- Revise an artifact in response to feedback.
- Work with private, workspace-visible, or public artifacts.
- Preserve content, comments, and version history for later sessions.
- Use Derive’s live artifact previews and shared review workflow.

The repository excerpt does not list individual MCP tool names or their full input schemas, so integrations should rely on the server’s published MCP instructions for exact calls.

## Limitations and notes

Derive is licensed under FSL-1.1-ALv2. The hosted endpoint requires the client to support the documented remote connection and OAuth flow. Local operation requires Node.js tooling capable of running the npm package.

The anonymous draft path is useful for publishing without an account, but the README distinguishes drafts from artifacts claimed into a workspace. Review, persistent ownership, and workspace access controls therefore depend on using the hosted service or a configured self-hosted instance.

_Full upstream README: https://allmcps.com/mcp/derive/readme_