writ-mcp

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 <key> 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). The hosted service is not live yet — until it is, always pass --url pointing at your own coordinator. 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": "<YOUR_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 coordinator, not by this package:

Tool	What it does
writ_list_workflows	Your saved workflows — plus a run_<name> tool per workflow
writ_run_workflow	Run one and wait for the extracted data
writ_workflow_data	Read a workflow's accumulated data table
writ_search_data	Search across everything already collected
writ_export_data	Export a workflow's data as CSV/JSON
writ_workflow_runs	Run history and status
writ_set_schedule	Schedule a workflow (interval / daily / weekly)
writ_expose_workflow_api	Publish a workflow as a callable REST endpoint
writ_crawl_site / writ_crawl_status	Start and poll a distributed site crawl
writ_create_automation	Event → run-workflow / notify chains
writ_create_monitor / writ_wire_monitor	Watch a page and react to changes

Every target additionally exposes a build family — writ_browser_use, writ_record_website, writ_build, writ_website_to_api, then writ_browser_act / _context / _network / _save / _cancel. 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 workflow's own generated 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:

Tool	What it does
writ_saved_crawls	List saved crawls. Check here before crawling a site again.
writ_run_saved_crawl	Run one, reusing recent data when max_age allows.
writ_saved_crawl_data	Read what one already collected, at any age. Never crawls.

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.

If a tool call times out

It comes back as status: "running" with retryable: true. The run was not cancelled — calling the tool again starts a second run. Wait, then retry with a max_age wide enough to pick up the first run's result once it lands.

Configuration

Flags take precedence over environment variables.

Flag	Env	Default	Purpose
--url	WRIT_COORDINATOR_URL / WRIT_URL	https://api.usewrit.app	Target base URL. A URL whose path is already /mcp or /mcp/<slug> is used verbatim.
--api-key	WRIT_API_KEY	— (required)	Key for Authorization: Bearer. Prefer the env var.
--insecure	WRIT_INSECURE_TLS=1	off	Accept a self-signed local-CA cert. Private networks only.
--timeout	WRIT_MCP_TIMEOUT_MS	600000	Per-request timeout (ms); covers long writ_run_workflow waits.
--help / --version	—	—	Print usage or version and exit.

HTTPS with a local CA (self-host): trust the CA (recommended) and use the https:// address, or set NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Use --insecure only for localhost testing — it disables certificate verification entirely, which exposes your key to a man-in-the-middle.

Security

This process exists to carry a credential, so everything that could expose one is made loud rather than convenient. Full detail in SECURITY.md.

• The key goes to --url and nowhere else. No telemetry, no analytics, no update check. Zero dependencies means there is no transitive code in the process that could phone home — and CI fails the build if that ever changes.
• Redirects are never followed. Replaying your Authorization header to whatever origin a Location header names would hand your key to a host you didn't choose. A 3xx becomes an error telling you to point --url at the final URL.
• Credentials in a URL are redacted from every diagnostic. MCP clients write a server's stderr to a log file on disk; https://user:pass@host/ would otherwise be written down in plaintext.
• Loud warnings, on stderr, for every way a key leaks: TLS verification disabled, plaintext http:// to a non-loopback host, or a key passed on the command line.
• Retries never double-run a workflow. Only read-only methods are retried; tools/call is sent exactly once, because a retry could re-execute a side effect the connector cannot see.
• Responses are bounded at 32 MB, so a broken endpoint can't grow this process until the OS kills your session.
• No request is ever left unanswered — a hung MCP client is a denial of service on your assistant, and that is the failure this connector works hardest to make impossible.

Scope your keys. Give a key only workflows:read / workflows:execute unless a tool you actually use needs more.

Verifying what you install

Releases are published from CI with npm provenance, so the tarball is cryptographically linked to the commit and workflow that built it:

npm audit signatures

Troubleshooting

Symptom	Cause and fix
Unauthorized: … rejected the API key	The key is wrong, disabled, or lacks scope. Recreate it under Settings → Developers with workflows:read / workflows:execute.
Cannot reach …	Wrong --url, or the target is down. For a self-signed cert see the local-CA note above.
… redirected (HTTP 301)	Your reverse proxy redirects (usually http → https). Point --url at the final URL.
The API key contains characters that cannot be sent in an HTTP header	A newline or control character got into the key — usually a copy-paste artifact. Re-copy it.
No tools listed	You have no saved workflows yet, or the key can't read them. The static writ_* tools appear regardless.
Client won't connect, no error	Read the connector's stderr — your client logs it. Claude Code: ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-<name>/.

Status

Self-hosted coordinator	Supported and verified end to end.
Published /mcp/<slug> endpoints	Supported.
Writ Cloud (https://api.usewrit.app, the no---url default)	Not live yet. The hosted service has not launched; the hostname does not resolve. Pass --url until it does.

Development

npm test

No dev dependencies — the suite uses Node's built-in node:test and drives the real index.js as a subprocess against a mock MCP server, exercising the same stdio path an MCP client uses. It runs in about six seconds. npm publish runs it automatically via prepublishOnly.

See CONTRIBUTING.md — note the two hard rules: zero dependencies, permanently, and no tool logic here.

The rest of Writ

usewrit/writ	The self-host coordinator — web UI, API, your data. Start here.
usewrit/writ-agent	The Rust fleet worker that does the actual browsing.
writ-mcp (this repo)	The MCP connector.

License

MIT — see LICENSE.

This package is deliberately permissive because it runs inside your MCP client, not inside the coordinator, so it has to be embeddable anywhere. The coordinator it talks to is AGPL-3.0-only; the two licenses are not interchangeable.