Writ Cloud

Your saved browser workflows, as tools your assistant can call.

Quick start · Tools · Configuration · Security · Troubleshooting · Contributing

writ-mcp connects a stdio MCP client — Claude Code, Claude Desktop, Cursor, Windsurf, Codex — to Writ, so the browser workflows you already recorded become tools your assistant can call: run them, read the data they collected, search past results, schedule them, expose them as REST endpoints, and kick off site crawls.

It is a transparent stdio↔HTTP proxy and nothing else. Every tool, schema and rule lives server-side, so what you get always matches what your instance can do — and a new tool never requires upgrading this package. Zero dependencies, one file, Node core only.

Clients that speak Streamable HTTP natively don't need this at all — point them

straight at the /mcp endpoint with an Authorization: Bearer header.

Quick start

1. Get an API key. In the Writ app: Settings → Developers → API keys. Keys look like wt_….

2. Add the server.

Against a self-hosted coordinator:

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://writ.example.com

Against a coordinator on this machine:

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url http://localhost:8000

Against a published per-workflow endpoint (an "Expose as MCP" slug URL is used verbatim — no path rewriting):

claude mcp add my-tools -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://mcp.example.com/mcp/my-tools

3. Check it.

claude mcp list

Writ Cloud is the default target when you pass no --url

(https://api.usewrit.app). Pass --url to point the connector at your own

coordinator instead. See Status.

Pass the key through the environment, not the command line. --api-key

works, but it puts your key in the process's argument list where any local

process can read it via ps, and your shell records it in history. The

connector prints a note when you use it.

Your running coordinator also hands out these one-liners, pre-filled, on its Connect page and at GET /api/mcp/connect-info:

Claude Desktop / Cursor (config file)

Add to claude_desktop_config.json (Claude Desktop) or ~/.cursor/mcp.json (Cursor). The env form is recommended — it keeps the key out of the argument list:

{

"mcpServers": { "writ-selfhost": { "command": "npx", "args": ["-y", "writ-mcp"], "env": { "WRIT_COORDINATOR_URL": "https://writ.example.com", "WRIT_API_KEY": " " } } } }

Without npm

A self-host install bundles this connector at connectors/writ-mcp. There is no build step, so you can run it straight from disk:

node /path/to/writ/connectors/writ-mcp/index.js --url https://writ.example.com

It coexists with the other Writ servers. Each surface registers under its

own slug on purpose — the desktop app is writ, Writ Cloud is writ-cloud, a

self-hosted coordinator is writ-selfhost — and each identifies itself to the

assistant with a distinct title. Keep any combination connected at once.

Tools you get

Served by the server you connect to, not by this package, so a new server tool reaches you without a connector update. Writ Cloud lists the 39 tools below; a self-hosted coordinator lists the ones marked in its column.

The build tools (writ_browser_use, writ_record_website, writ_website_to_api, then writ_browser_act / _context / _network / _save / _cancel) are on both targets; neither has a writ_build tool, so use writ_record_website. Your assistant opens a real browser, drives it turn by turn, and saves the session as a reusable workflow that afterwards replays with no model in the loop. Writ Cloud runs it on Writ's fleet; a self-hosted coordinator runs it on your own fleet agent. Either way your assistant is the brain — no second model key is involved.

Reusing a recent result (max_age)

Running a workflow drives a real browser, so asking the same question twice in one session costs two full runs and two waits. Every workflow tool takes an optional `max_age` (seconds) meaning *a recent answer is good enough*:

{ "name": "run_price_check", "arguments": { "sku": "B0C123", "max_age": 300 } }

• omitted or `0` — always run fresh (the default; nothing goes stale on its own).
• `N` — reuse a result younger than N seconds, otherwise run.

A reused answer carries _cache: {hit: true, age_seconds: N} so the assistant can tell how current it is.

max_age works identically against Writ Cloud and a self-hosted coordinator, and on a pinned workflow's own run_ tool as well as writ_run_workflow.

Calling a saved crawl (writ_run_saved_crawl)

A whole-site crawl is slow and metered, so re-crawling to answer the same question is the most expensive mistake an assistant can make. A saved crawl is a stored crawl configuration with a stable name, and the same max_age contract applies to it:

{ "name": "writ_run_saved_crawl", "arguments": { "crawl": "docs", "max_age": 86400 } }

• hit — the pages that crawl already collected come back inline, instantly, with nothing crawled and nothing metered.
• miss — the site is crawled again with the *saved* settings, and you get a crawl id to poll with writ_crawl_status (a crawl outlives a single tool call).

Three tools cover the surface:

To create one, pass save_as to writ_crawl_site — that saves the settings *and* runs them, so the crawl becomes callable by REST as well. Re-using the same save_as updates that saved crawl instead of piling up duplicates. Saving needs an admin-scoped credential (it creates reusable, callable configuration); running one needs only run.

Sites behind a login (writ_personas)

A persona is a saved sign-in identity — username, credentials sealed server-side, optional 2FA, and a warm signed-in session. writ_personas lists yours (with per-persona readiness), inspects one (get), refreshes its session by running its login workflow (sign_in), or has the AI record the sign-in flow once so the persona can sign itself in from then on (record_login). The assistant then passes a persona_id to writ_run_workflow (and each pinned run_ tool), writ_crawl_site, or writ_scrape — p