Skip to content
usewritPublic

About

The open-source MCP bridge to Writ Cloud: your website APIs as tools your AI assistant can call, with a wt_ API key. Zero dependencies, one file.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

writ-mcp: your Writ APIs, as tools your AI assistant can call. usewrit.app

CI npm version License: MIT Node 18+ Zero dependencies Published with npm provenance PRs welcome

Your Writ APIs, as tools your AI assistant can call.

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/mcp directly 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.

Quick start

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-mcp

Codex:

codex mcp add writ-cloud --env WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp

A 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-stories

3. Check it.

claude mcp list

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.

Claude Desktop, Cursor, Windsurf (config file)

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>" }
    }
  }
}

Without npm

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.js

Writ Desktop

Writ 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 is writ-cloud. Keep both connected at once.

Tools you get

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.

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 on a pinned workflow's own run_<name> tool as well as on 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.

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_<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.

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: 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.

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 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>/.

Status

Writ Cloud (https://api.usewrit.app, the no---url default) Supported.
Per-workflow MCP servers (https://mcp.usewrit.app/mcp/<org>/<slug>) Supported.

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.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.

License

MIT — see LICENSE.

This package is deliberately permissive because it runs inside your MCP client, so it has to be embeddable anywhere.

About

The open-source MCP bridge to Writ Cloud: your website APIs as tools your AI assistant can call, with a wt_ API key. Zero dependencies, one file.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages