wraft-mcp

The mcp server for Wraft, the open-source document lifecycle platform. It gives Cursor, Claude Code, Claude Desktop, and any other MCP client a curated tool set for running the document lifecycle end to end:

• Scaffold the pipeline — create themes, layouts, approval flows, and content types (variants) with their fillable fields

• Author templates — write a document body in markdown; [Field Name] placeholders become fillable fields

• Produce documents — fill a template with values, build the PDF, and move the document through its approval flow

• Automate — wire adaptor steps (build document, email, HTTP, conditions) into workflow DAGs with conditional edges

One shared tool set, two ways to run it:

• stdio (wraft-mcp) — your MCP client spawns the server locally; auth via env vars

• Streamable HTTP (wraft-mcp-http) — a hosted, stateless service at /mcp; auth via per-request x-api-key header

Setup

Local (stdio) — recommended for individuals. Add to your MCP client config:

{
  "mcpServers": {
    "wraft": {
      "command": "npx",
      "args": ["-y", "wraft-mcp@0"],
      "env": {
        "WRAFT_BASE_URL": "https://app.your-wraft.example",
        "WRAFT_API_KEY": "wraft_..."
      }
    }
  }
}

Remote (hosted HTTP):

{
  "mcpServers": {
    "wraft": {
      "url": "https://mcp.your-domain.example/mcp",
      "headers": { "x-api-key": "wraft_..." }
    }
  }
}

Client timeouts: build_document can run up to 120 s. Raise your MCP client's tool-call timeout accordingly (Cursor: "timeout" per server entry) or builds will appear to fail while still completing server-side.

During development (before npm publish): "command": "node", "args": ["/ABS/PATH/wraft-mcp/dist/index.cjs"].

Related MCP server: task-orchestrator

Tools

Documents

Scaffolding

Notes for agents

• Pagination: list_* tools accept page and return page_number / total_pages / total_entries — paginate before concluding something doesn't exist. Exceptions: list_flow_states and list_field_types return plain arrays.

• Field machine names: create_document_from_template takes fields keyed by machine name — the field's name lowercased, apostrophes stripped, spaces → _, other characters removed ("Client Name" → client_name). Get field names from get_data_template (under content_type.fields).

• Writes are not idempotent: a timed-out create_* or build_document call may still have completed. List or fetch before retrying — a blind retry creates a duplicate.

• No update/delete for scaffolding: themes, layouts, flows, content types, and workflows can be created but not modified or removed via MCP — clean up mistakes in the Wraft web UI. Workflow triggers also need the UI (execution is available via execute_workflow).

API keys

• Keys are unscoped. A Wraft API key carries its owner's full role permissions — the curated tool list limits what the agent can reach, not what the credential could do elsewhere. Create a dedicated least-privilege user for MCP keys.

• IP-whitelisted keys don't work via the hosted server. Wraft sees the MCP server's IP, not yours, so whitelisted keys get 403 ip_not_whitelisted. Use a key without an IP whitelist for hosted access, or run stdio from an allowed machine. Do not whitelist the MCP server's egress IP — that nullifies the control for everyone behind the proxy.

• Keys are never logged by this server; redaction of x-api-key / authorization must also be configured in any logging/APM middleware added around it.

Hosted deployment

See deploy/README.md — Docker image, env reference, ready-made compose + nginx edge, and the hosting checklist.

Development

npm install
npm test          # unit tests
npm run typecheck
npm run build     # dist/index.cjs (stdio) + dist/http.cjs (HTTP)

# live smoke against a running Wraft (runs whoami by default; exits non-zero on tool errors):
WRAFT_BASE_URL=http://localhost:4000 WRAFT_API_KEY=wraft_... npm run smoke
# or pass tool calls:
node scripts/smoke.mjs dist/index.cjs '{"name":"list_flows","arguments":{}}'

# optional pre-push gate (typecheck + tests + build before every push):
git config core.hooksPath .githooks

License

AGPL-3.0-only — see LICENSE.md.