usewrit.app · Docs · Quick start · Tools · Configuration · Security · Troubleshooting · Contributing
writ-mcp is the open-source stdio bridge to the MCP server of Writ,
the service that gives you your own API to any website. It connects Claude Code, Claude Desktop,
Cursor, Windsurf, Codex or any stdio MCP client to Writ Cloud with a wt_ API key, so your
assistant can turn a website into an API, run the APIs and workflows you saved, read pages, crawl
sites, watch pages for changes and schedule jobs.
It is a transparent stdio↔HTTP proxy and nothing else. Every tool, schema and rule lives server-side, so a new tool never requires upgrading this package. Zero dependencies, one file, Node core only.
You may not need it. A client that supports remote MCP servers connects to
https://api.usewrit.app/mcpdirectly and signs in with OAuth: no key, no package. See Connect an AI assistant. Use writ-mcp when your client only runs local commands, or when you prefer a fixed API key.
1. Get an API key. Sign in at usewrit.app, then open Developers → API
Keys. A key starts with wt_ and is shown once.
2. Add the server.
Claude Code:
claude mcp add writ-cloud -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcpCodex:
codex mcp add writ-cloud --env WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcpA per-workflow MCP server (the URL a workflow's Expose as MCP gives you) is used verbatim, with no path rewriting:
claude mcp add my-tools -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://mcp.usewrit.app/mcp/your-org/top-stories3. Check it.
claude mcp listPass the key through the environment, not the command line.
--api-keyworks, but it puts your key in the process's argument list where any local process can read it viaps, and your shell records it in history. The connector prints a note when you use it.
Add to claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json (Cursor) or
~/.codeium/windsurf/mcp_config.json (Windsurf). The env form keeps the key out of the argument
list:
{
"mcpServers": {
"writ-cloud": {
"command": "npx",
"args": ["-y", "writ-mcp"],
"env": { "WRIT_API_KEY": "<YOUR_API_KEY>" }
}
}
}There is no build step, so you can run a checkout of this repository straight from disk:
WRIT_API_KEY=<YOUR_API_KEY> node /path/to/writ-mcp/index.jsWrit Desktop runs the same kind of tools on your own computer, for
free, and has its own local MCP server: open MCP & APIs in the app and use its one-click install.
It does not need this package. To reach a linked Writ Desktop from Writ Cloud instead, use the
writ_devices tool.
It coexists with the other Writ servers. Each surface registers under its own name on purpose: Writ Desktop is
writ, Writ Cloud iswrit-cloud. Keep both connected at once.
Served by Writ Cloud, not by this package, so a new tool reaches you without a connector update. The full reference is MCP tools.
| Tool | What it does |
|---|---|
writ_website_to_api |
Turn a website into a callable API |
writ_discovery_status |
Follow an API build to its result |
writ_list_workflows |
Your saved APIs and workflows (a run_<name> tool is added only for workflows you pin) |
writ_run_workflow |
Run one and wait for the extracted data |
writ_pin_workflow_tool |
Pin or unpin a workflow as its own run_<name> tool (off by default, capped; everything still runs via writ_run_workflow) |
writ_update_workflow |
Read a workflow's outline or edit it in place (settings, steps, functions, its agent skill) |
writ_diagnose_http_workflow |
Show what every request of a run was answered with, and whether it ran without a browser |
writ_create_http_extraction |
Author a multi-request browserless extraction from captured requests |
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 or 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_scrape |
Read a page, or several, as clean markdown, or a listing's top N |
writ_crawl_site / writ_crawl_status |
Start and follow a site crawl |
writ_crawl_files |
The original documents a crawl captured (PDFs, office files, images) |
writ_saved_crawls / writ_run_saved_crawl / writ_saved_crawl_data |
Saved crawls (see below) |
writ_update_saved_crawl |
Inspect or change a saved crawl's settings |
writ_personas |
See your saved sign-in identities and get them ready (see below) |
writ_payment |
Pay with a card the user approves; Writ places the order once they confirm |
writ_devices |
Your linked Writ Desktops: list them, or point this connection at one |
writ_create_automation |
Event or clock → run a workflow, notify, or wake an agent |
writ_list_webhooks |
Your inbound webhook URLs and the automations they fire |
writ_create_monitor / writ_wire_monitor |
Watch a page and react to changes |
writ_browser_use |
Open a real browser your assistant drives turn by turn |
writ_record_website |
Record a repeatable task as a workflow |
writ_browser_act / _context / _network / _save / _cancel |
Act in the browser, read the page and its network calls, save or close the session |
writ_browser_compose |
Define named functions, inputs and explicit steps in a session |
writ_browser_ask_user |
Hand a CAPTCHA, a code or a decision to the user in the live browser |
writ_browser_sessions |
Open browser sessions you can resume |
writ_help |
Any tool's full reference, or the complete guide |
The build tools (writ_website_to_api, writ_browser_use, writ_record_website, then
writ_browser_act / _context / _network / _save / _cancel) let your assistant open a real
browser, drive it turn by turn, and save the result as a reusable API that afterwards runs with no
model in the loop. It runs on Writ's servers, or on your own computer through a linked Writ Desktop.
Either way your assistant is the brain: no second model key is involved.
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:
- omitted or
0— always run fresh (the default; nothing goes stale on its own). N— reuse a result younger thanNseconds, otherwise run.
A reused answer carries _cache: {hit: true, age_seconds: N} so the assistant can
tell how current it is.
max_age works on a pinned workflow's own run_<name> tool as well as on
writ_run_workflow.
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.
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_<name> tool), writ_crawl_site, or writ_scrape — plus writ_browser_use
on Writ Cloud — and the task runs signed in, with 2FA codes minted server-side.
By design the connector can only use personas, never manage them: creating, editing or deleting one involves credentials, and no credential or one-time code ever crosses the MCP connection in either direction. Personas are created in the Writ app.
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.
Flags take precedence over environment variables.
| Flag | Env | Default | Purpose |
|---|---|---|---|
--url |
WRIT_COORDINATOR_URL / WRIT_URL |
https://api.usewrit.app |
Target base URL: Writ Cloud by default. A URL whose path is already /mcp or /mcp/<slug> is used verbatim. (The env name is historical.) |
--api-key |
WRIT_API_KEY |
— (required) | Key for Authorization: Bearer. Prefer the env var. |
--insecure |
WRIT_INSECURE_TLS=1 |
off | Accept a self-signed certificate. Local testing 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. |
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
--urland 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
Authorizationheader to whatever origin aLocationheader names would hand your key to a host you didn't choose. A 3xx becomes an error telling you to point--urlat 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/callis 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.
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| Symptom | Cause and fix |
|---|---|
Unauthorized: … rejected the API key |
The key is wrong, disabled, or lacks scope. Recreate it under Developers → API Keys with workflows:read / workflows:execute. |
Cannot reach … |
Wrong --url, or the network blocks the connection. Leave --url out to use Writ Cloud. |
… redirected (HTTP 301) |
The URL 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 | The connector could not reach Writ, or the key was rejected — see the rows above. With a working connection the static writ_* tools are always listed, even before you save a workflow. |
A workflow has no run_<name> tool |
Derived tools are opt-in and off by default. Pin the workflow with writ_pin_workflow_tool (or the app's Expose as MCP tool switch) and it appears on the next tools/list, up to 20 per account. Every workflow runs through writ_run_workflow either way. |
| 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>/. |
Writ Cloud (https://api.usewrit.app, the no---url default) |
Supported. |
Per-workflow MCP servers (https://mcp.usewrit.app/mcp/<org>/<slug>) |
Supported. |
npm testNo 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.
| usewrit.app | Writ Cloud: build, run and schedule your website APIs. Start here. |
| usewrit/writ-plugins | The Writ plugin for Claude, Codex, Cursor, Gemini CLI and GitHub Copilot: the MCP server over OAuth, plus skills. |
| usewrit/writ-sdks | Client SDKs for TypeScript, Python, Go and Rust. |
| usewrit/writ-desktop | Writ Desktop downloads and issue tracker. |
| usewrit/writ-agent | Connect a computer or server you control to your Writ account. |
| writ-mcp (this repo) | The MCP bridge. |
MIT — see LICENSE.
This package is deliberately permissive because it runs inside your MCP client, so it has to be embeddable anywhere.
{ "name": "run_price_check", "arguments": { "sku": "B0C123", "max_age": 300 } }