wraft-mcp

MCP server for Wraft — lets AI agents (Cursor, Claude Code, Claude Desktop) discover and run curated document-lifecycle tools over Wraft's /api/v1 REST API.

Two entrypoints, one shared tool set:

• stdio (wraft-mcp) — the 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

Tools

Tool	What it does
list_content_types	Content types (document variants) with their fields
list_data_templates / get_data_template	Pre-authored templates with fillable fields
create_data_template	Author a template from markdown — [Field Name] placeholders become fillable holder fields (must match the content type's fields)
list_documents / get_document	Documents in the organisation
create_document_from_template	Preferred create path: fills a template's placeholders from a field-values map and creates the document
create_document	Raw-payload create (escape hatch)
update_document	Update content (creates a version)
build_document	Generate the PDF (synchronous, up to ~2 min)
transition_document_state	Move a document through its approval flow
list_flows / get_flow / list_flow_states	Approval flows and their states
whoami	Verify the key: user, email, organisation, roles

All list_* tools accept page and return page_number / total_pages / total_entries — paginate before concluding something doesn't exist.

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

Write tools are not idempotent

A timed-out create_* or build_document call may still have completed on the server. List or fetch before retrying — a blind retry creates a duplicate document or another build version.

Cursor / Claude Code configuration

Local (stdio) — recommended for individuals:

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

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

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.

API keys: what to know

• Keys are unscoped. A Wraft API key carries its owner's full role permissions — this server's 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

docker build -t wraft-mcp .
docker run -p 8080:8080 \
  -e WRAFT_BASE_URL=https://app.your-wraft.example \
  -e ALLOWED_ORIGINS=https://your-web-agent.example \
  wraft-mcp

Env	Meaning
WRAFT_BASE_URL	Upstream Wraft instance. Must be https:// (startup assertion; http://localhost allowed for local testing only). Clients cannot override it — x-wraft-base-url is rejected.
PORT	Listen port (default 8080)
ALLOWED_ORIGINS	Comma-separated browser origins. Fail-closed: unset = every request carrying an Origin header is rejected (DNS-rebinding defense). Header-less clients (Cursor) are unaffected.
MAX_BODY_BYTES	Request body cap (default 2 MiB)

Endpoints: POST /mcp (MCP, stateless — POST only), GET /healthz (probes).

The server is stateless (no MCP sessions): run any number of replicas with no sticky routing; x-api-key is read on every request and forwarded only to WRAFT_BASE_URL.

Hosting checklist

1. Build and push the image; deploy with the env above
2. DNS mcp.<domain> + TLS at the edge
3. Edge rate limit (required) and max request body size
4. Ingress read timeout ≥ 120 s (the build_document upstream timeout)
5. Wire GET /healthz into liveness/readiness probes
6. Smoke-test from Cursor with whoami, then run one create_document_from_template → build_document → transition_document_state chain

Development

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

Publishing (maintainers)

Publish only via CI with a scoped npm token, 2FA on the account, and npm publish --provenance. Only the wraft-mcp stdio bin is meant for the registry; wraft-mcp-http ships in the Docker image. After publishing, verify the documented pinned npx config works on a clean machine.

License

AGPL-3.0-only — see LICENSE.md.