# Workplane

> The home for your agent's work. Save, share, and hand off — to a teammate or the next Claude session.

Workplane (workplane.co) is a persistent workspace for AI agents. Agents publish artifacts (also called projects) — code, designs, PRDs, research, interactive playgrounds — and humans or other agents open them at a URL. One shareable address per artifact works in the browser and in MCP.

## Install

Workplane integrates via **MCP** (Model Context Protocol). Native tool-calling inside any MCP-capable client (Claude Code, Claude Desktop, Codex, Devin, Cursor, Windsurf, Zed, VS Code Copilot). No binary to install.

### Add the MCP server

Add a new MCP server to your client's settings:
- **Name:** Workplane
- **URL:** https://workplane.co/api/mcp

Or paste this into your client config:

```
{
  "mcpServers": {
    "workplane": {
      "type": "http",
      "url": "https://workplane.co/api/mcp"
    }
  }
}
```

Authenticate when the client prompts you — the browser opens for sign-in, you approve once, the tools stay available across sessions.

### Optional: install the skill (Claude Code / skills-capable clients)

```
mkdir -p ~/.claude/skills/workplane
curl -fsSL https://workplane.co/skill.md -o ~/.claude/skills/workplane/SKILL.md
```

Reload your skills / plugins afterward. The skill documents publish/review flows on top of the MCP tools.

## Verify

List your tools — you should see `createArtifact`, `write`, `read`, `requestUpload`, `saveVersion`, `ls`, `edit`, `rm`, `downloadZip`, `describeArtifact`, `updateArtifactAccess`, `listVersions` in the `workplane` namespace (12 tools). Once you see them, stop and tell the user you're ready — they'll hand you an artifact to work on next.

If any step fails, stop and report exactly what you saw. Don't guess. Don't silently fall back to another path.

## Tools

The MCP server exposes Workplane's REST API as tools:

- `createArtifact` — create a new artifact. Optionally seed it with one initial text file in the same call.
- `ls` — list children of any address (pass `depth` 1–4 to recurse, default 1; folder entries then carry a nested `children` array). With no address, returns your profile + visible artifacts.
- `read` — for files, stream the content (text inline, binary as signed URL); for profiles / artifacts / versions / folders, return metadata (size, content-type, sha256, visibility, timestamps) — no bytes.
- `write` — create or overwrite a file. Text via `content`. For binary or large text, do the two-step: `requestUpload({ address })` → PUT bytes to the returned signed URL → `write({ address, uploadId })`. Intermediate folders are auto-created. Cap: 25 MiB.
- `edit` — apply `oldString` / `newString` replacements to an existing UTF-8 text file.
- `requestUpload` — mint a signed PUT URL for a single out-of-band upload. Pair with `write({ uploadId })`. Bytes never enter the MCP payload. URL expires in 15 minutes.
- `downloadZip` — bulk download an artifact / version / folder / file as a 5-minute signed-URL zip.
- `rm` — remove a file or folder (recursive). Refuses artifacts (humans only), profiles, and items inside saved versions.
- `saveVersion` / `listVersions` — freeze WIP as an immutable named snapshot, or list past snapshots.
- `describeArtifact` — update an artifact's name / description.
- `updateArtifactAccess` — flip visibility (`public` / `private`), `grant` a member (`{ user, role }` where `user` is an email or 5-char short_id and `role` is `editor` | `viewer`), or `revoke` a member. Any combination in one call.

Addresses are of the form `<owner-short-id>/<artifact-slug>[/<path>]` for WIP, or `<owner-short-id>/<artifact-slug>/@<version-name>[/<path>]` for a saved snapshot.

## Quickstart: publish a body of work in 4 calls

```text
1. createArtifact({ name: "review-2026-05-07", description: "...", visibility: "private" })
   → returns the artifact address, e.g. "abc12/review-2026-05-07"

2. write({ address: "abc12/review-2026-05-07/SUMMARY.md", content: "..." })
   write({ address: "abc12/review-2026-05-07/decisions.md", content: "..." })
   …binary or large text (image, PDF, big file):
     a. requestUpload({ address: "abc12/review-2026-05-07/screenshot.png" })
     b. curl -X PUT --data-binary @screenshot.png -H "Content-Type: image/png" "<upload_url>"
     c. write({ address, uploadId })

3. saveVersion({ artifact: "abc12/review-2026-05-07", name: "v1" })

4. updateArtifactAccess({ artifact, visibility: "public" })
   → share the URL: https://workplane.co/abc12/review-2026-05-07
```

Iterate by writing more files, then `saveVersion` again. The previous version stays immutable.

## What Workplane Is

- A persistent workspace that survives individual agent sessions
- A place to save agent output and share it with a human via a link
- A handoff surface so one agent session (or agent) can pick up where another left off
- An addressable filesystem: every artifact, folder, file, and version has a stable URL
- A review primitive: save a version of a moment to create an immutable, linkable snapshot

## What Workplane Is Not

- Not a chat interface or an agent runtime — bring your own agent
- Not a replacement for your editor or IDE — read content via MCP and work with normal tools
- Not a doc wiki — structured collaboration happens in the files themselves, not in rich-text pages

## Links

- Website: https://workplane.co
- API: https://api.workplane.co
- MCP server: https://workplane.co/api/mcp
- Skill definition: https://workplane.co/skill.md
- Skills repo: https://github.com/work-plane/workplane-skills