wraft-mcp
This server provides MCP tools to manage Wraft documents, templates, and approval flows via the Wraft REST API. Key capabilities:
Documents: Create from templates (preferred) or raw markdown, update, list/filter, retrieve, build PDFs, and transition approval states.
Templates & Content Types: Create data templates from markdown with placeholders, list/retrieve templates, list content types (e.g., NDA, Offer Letter) to inspect fields.
Approval Flows: List flows, get flow details, list flow states, and move documents through workflows.
Identity: Verify API key via
whoamito get user, email, organization, roles.Operational: Pagination on all list tools; field machine names are lowercased with spaces to underscores and stripped special chars. Write operations are not idempotent: check before retrying timed-out calls. Supports stdio and Streamable HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wraft-mcp Create a document from the 'Project Proposal' template."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 fieldsProduce 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 varsStreamable HTTP (
wraft-mcp-http) — a hosted, stateless service at/mcp; auth via per-requestx-api-keyheader
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: fallengineer-us-mcp
Tools
Documents
Tool | What it does |
| Documents in the organisation |
| Preferred create path: fills a template's placeholders from a field-values map and creates the document |
| Raw-payload create (escape hatch) |
| Update content (creates a version) |
| Generate the PDF (synchronous, up to ~2 min) |
| Move a document through its approval flow |
| Pre-authored templates with fillable fields |
| Author a template from markdown — |
Scaffolding
Tool | What it does |
| Content types (document variants) with their fields |
| Create a variant with fields, wired to a layout, flow, and theme |
| Field types (String, Text, Date, …) for |
| Approval flows and their states |
| Create a flow (default Draft → Publish states; custom states/approvers need the Wraft UI) |
| Themes: font + colors (font-file assets must pre-exist; pass ids) |
| Layouts: engine, page-template slug ( |
| Uploaded assets by type (theme fonts, layout letterheads) — source of ids for |
| Automation workflows (DAGs of adaptor steps) and their full structure |
| Create a workflow: steps (adaptor + config, referenced by key) connected by edges; triggers need the Wraft UI |
| Run a workflow with trigger data and get per-step results (synchronous) |
| Run history and per-step results of a run |
| Verify the key: user, email, organisation, roles |
Notes for agents
Pagination:
list_*tools acceptpageand returnpage_number/total_pages/total_entries— paginate before concluding something doesn't exist. Exceptions:list_flow_statesandlist_field_typesreturn plain arrays.Field machine names:
create_document_from_templatetakesfieldskeyed by machine name — the field's name lowercased, apostrophes stripped, spaces →_, other characters removed ("Client Name"→client_name). Get field names fromget_data_template(undercontent_type.fields).Writes are not idempotent: a timed-out
create_*orbuild_documentcall 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/authorizationmust 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 .githooksLicense
AGPL-3.0-only — see LICENSE.md.
Available Tools
15 toolsbuild_documentA
Generate the document's PDF. Runs synchronously and can take up to two minutes — do not retry a timed-out build without checking get_document first (the build may have completed; retrying creates another build version). Fails with 422 if the document is locked (approval flow complete).
Inputs: id (required), naration.
create_data_templateA
Author a new data template for a content type from markdown. Write [Field Name] placeholders in the body and title_template — they become fillable holder fields, and MUST match the content type's field names (see list_content_types). Supported markdown: #-###### headings, paragraphs, - bullets, 1. numbered lists, > quotes, ---, bold, italic. The result reports any placeholders that didn't match a field (left as plain text) — fix and recreate if needed. NOT idempotent.
Inputs: title (required), body_markdown (required), content_type_id (required), title_template.
create_documentA
Create a document from a raw payload (escape hatch — prefer create_document_from_template). serialized must be an object: {title, body (markdown), serialized (JSON-encoded ProseMirror doc), fields (JSON-encoded field-values map)}. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
Inputs: raw (required), serialized (required), content_type_id (required), meta, +1 more.
create_document_from_templateA
PREFERRED way to create a document: fills a data template's placeholder fields and creates the document in one step. Get field machine names from get_data_template (content_type.fields → lowercase name, spaces to underscores, e.g. "Client Name" → client_name). NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
Inputs: fields (required), data_template_id (required), meta, title.
get_data_templateA
Get one data template with its content type and fields. The content_type.fields list gives each field's name; the machine name for create_document_from_template is the lowercased name with spaces as underscores and other characters stripped (e.g. "Client Name" → client_name).
Inputs: id (required).
get_documentA
Get one document with its content, content type, state, versions, and approval systems.
Inputs: id (required).
get_flowC
Get one flow with its states.
Inputs: id (required).
list_content_typesA
List Wraft content types (document variants such as NDA, Offer Letter). Each includes its fields (name, type, required) — field names determine the machine names used by create_document_from_template. Paginated.
Inputs: name, page, sort.
list_data_templatesA
List Wraft data templates (pre-authored document bodies with fillable placeholder fields). Use a template id with get_data_template or create_document_from_template. Paginated.
Inputs: page, title.
list_documentsA
List documents (content instances) in the organisation. Paginated — check total_pages and paginate before concluding a document doesn't exist.
Inputs: page, sort, state, instance_id, +2 more.
list_flowsA
List Wraft approval flows. Paginated.
Inputs: name, page, sort.
list_flow_statesA
List the states of a flow in order (returns a plain array, not paginated). Use a state's id with transition_document_state. Note: states can carry approver requirements — a transition may be rejected if the API key's user is not an eligible approver.
Inputs: flow_id (required).
transition_document_stateA
Move a document to another state in its flow. Get valid state ids from list_flow_states (the document's flow is on its content type). Transitions may be rejected if the flow requires an approver the API key's user is not.
Inputs: id (required), state_id (required).
update_documentA
Update a document's content. serialized has the same object shape as create_document. Fails if the document is no longer editable (approval flow complete). Metadata is NOT updated here. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
Inputs: id (required), raw (required), serialized (required), naration, +1 more.
whoamiA
Get the current user for the configured API key (name, email, organisation, roles). Use to verify connectivity and see which organisation the key operates on.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target distinct resources and actions (documents, templates, flows, content types), with clear verb-prefixed names. The main potential confusion is between create_document_from_template and create_document, and between get_flow and list_flow_states, but the descriptions clarify their respective purposes well.
The majority follow a consistent verb_noun pattern: get_, list_, create_, update_, build_, transition_. The only outlier is 'whoami', a common utility convention, so it doesn't disrupt overall readability.
With 15 tools, the server sits at the upper end of the ideal range but every tool serves a distinct necessary function for document management, template authoring, and approval flows. No redundant or superfluous tools are present.
Core document lifecycle is covered: create (two ways), read, update, build PDF, and transition states. Missing delete operations for documents/templates and an update for data templates are minor gaps that agents can work around, but they don't prevent primary workflows.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for MDMA (Markdown Document with Mounted Applications) — interactive Markdown with forms, approval gates, tables, and more. Exposes the MDMA spec, authoring prompts, package metadata, and live docs to AI assistants so agents can author and integrate MDMA correctly.886 npm75MIT
- AlicenseNot gradedqualityCmaintenanceA sovereign, MIT-licensed MCP server for professional-service workflow tools that runs on your infrastructure with Ed25519 signing, enabling autonomous agents to discover and invoke tools securely.MIT
- AlicenseBqualityBmaintenanceMCP server that dynamically exposes each enabled ComfyUI workflow as a tool with JSON Schema, supports job submission with wait and idempotency, file uploads, and resource metadata, with both stdio and authenticated Streamable HTTP transports.36MIT
- FlicenseAqualityCmaintenanceExperimental MCP server for the wflow.com public API, enabling natural language operations on documents, registers, users, roles, and teams across one or many organizations.266 npm-