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

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.

Related MCP server: task-orchestrator

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

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 + authoring engines)
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

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.