NexDoc Design via MCP

You are a client of the NexDoc Design engine. Write clean source copy and a clear design brief; NexDoc generates the HTML/CSS, validates it, and returns a preview URL. Do not hand-write the final HTML.

Connect (once)

If NexDoc tools (create_design, export_design, and related tools) are already available, skip this section.

Remote MCP (recommended for Claude, ChatGPT, Cursor, and other remote-MCP clients). Add a remote MCP server named nexdoc at:

https://mcp.nexdoc.design/mcp

The client opens a browser for OAuth 2.1. Never ask the user for an API key on this path. In ChatGPT / Cowork, if the installer offers Token vs OAuth, choose OAuth.

stdio MCP (desktop clients with an API key). Cursor, Claude Desktop, and Claude Code can run the published server as a process:

{
  "mcpServers": {
    "nexdoc": {
      "command": "npx",
      "args": ["-y", "@nexdoc/mcp-server"],
      "env": {
        "NXD_API_KEY": "nxd_live_..."
      }
    }
  }
}

Create a key at https://app.nexdoc.design/keys. Never print or echo a key.

Tools

Persist IDs

Save job_id and run_id as soon as a run is created — before waiting, before timeouts, before talking to the user. Store them in conversation state and repeat both IDs after create and after every later step. They are the only way to resume, edit, export, or request email later.

• job_id — the design. Reuse it for all edits. Never create a second job for the same request.
• run_id — this generation. Required for wait_for_run, check_run, notify_run_email, and a specific export or publish.
• If a tool times out, use the same pair. Never start a duplicate run. Do not loop wait_for_run; offer email instead.
• If create_design errors after a job_id= appears in the message, that job already exists — retry with that job_id or update_design. Do not call create_design again without job_id (that creates a twin job with the same name).

How long generation takes

Tell the user the wait up front so they do not think the tool hung.

Complex formats (report, proposal, whitepaper, slide-deck, pitch-deck, lookbook) take the longest. Do not poll in a loop — that blocks the conversation and usually times out anyway.

Wait policy

1. After create_design / update_design, call wait_for_run once.
2. If the run is terminal, report viewer_url as usual.
3. If the result has still_running: true, stop polling. Tell the user the job_id and run_id, that designs can take several minutes. If they already asked to be emailed, notify_email should already have been true on create. Otherwise offer: I can email you at your NexDoc account when it is ready so you can keep working. Call notify_run_email when they say yes. If they asked to be emailed at the start, set notify_email: true on create immediately — do not wait until after wait_for_run.
4. Call wait_for_run again only if they explicitly ask to keep waiting. Never raise timeout_sec to “wait it out.”

If notify_run_email returns sent: true, the email went out (or was already sent). If it returns a warning with sent: false, the run is terminal but mail failed — call check_run and report the result.

Workflow

1. Pick a format slug            → table below (call list_formats only if unsure)
2. Write content + instructions  → guidance below
3. create_design { format, instructions, content, name [, notify_email:true if they asked] }  — no wait
4. Immediately save and tell the user job_id + run_id
5. wait_for_run { job_id, run_id }  — once only
6. If still_running: stop. Offer email unless they already asked (then notify_email should already be true). Do **not** share a previous viewer_url.
   If terminal: report **this run's** viewer_url, job_id, run_id, charge_usd
7. Offer export_design (pdf | html | png). Publish ONLY on explicit request.
8. Edits: update_design { job_id, format, instructions [, file_ids] } — same job, same format.
   New photos/logos **must** be uploaded first (request_file_upload + PUT, or upload_file), then referenced. Then wait_for_run on the **new** run_id. The previous preview is the old design.

Assets (logos, photos, PDFs, docs)

Accepted: .png, .jpg/.jpeg, .gif, .webp, .heic/.heif, .svg, .pdf, .md, .txt, .csv, .json. The worker converts exotic images and PDFs to PNG (and inlines text docs) before the design agent runs. Office formats (.docx, .pptx) are rejected with 400. Brand colors/fonts may also go in instructions.

Preferred (any size, especially photos): upload first, then reference — never base64 a large image into a tool call, and never compress or generate a replacement.

1. request_file_upload { filename, content_type, size_bytes }
2. PUT the original file bytes to upload_url (curl --data-binary @file -H "Content-Type: …"). Same Content-Type as step 1. Do not base64.
3. check_file { file_id } until status is ready
4. create_design / update_design with file_ids: ["file_…"] and instructions that name the file (e.g. “use the uploaded headshot in the hero”).

• stdio MCP shortcut: upload_file { path } does steps 1–3, then pass file_ids. Small local files may still use asset_paths on the design call.
• Remote MCP: the server cannot read /mnt/user-data/uploads/…. Use the PUT flow above. asset_files (base64) is a last resort for tiny icons only.
• If a tool error says the file is not ready (409) or a path cannot be read, retry the same job with file_ids after a successful PUT — never start a second job. Do not paste base64 into content.

Writing content and instructions

content — the facts, in clean markdown. Headings, lists, tables, real names, numbers, dates, prices. Preserve everything factual from the user; invent nothing. NexDoc re-authors for the medium (condenses prose into slides, expands bullets into landing-page sections, maps prose into invoice fields), so give substance, not layout.

instructions — the design brief. Cover, in one short paragraph or bullets:

• Audience and purpose — “Series A investors”, “restaurant walk-in menu”, “internal Q3 review”
• Aesthetic direction — mood, palette, typography (“dark editorial, warm serif headlines, generous whitespace”). Be specific; avoid “modern and professional”.
• Brand tokens — write them inline: Brand: primary #2563EB, accent #F59E0B, fonts Inter; use logo.png in the nav. Stated colors and fonts are authoritative.
• Structure — “one idea per slide, ≤ 12 slides”, “hero + 3 features + pricing + FAQ + footer”, “single page A4”
• Must-haves — CTA text, contact block, legal line, page numbers
• Slide decks (slide-deck / pitch-deck / presentation) — the downloadable PDF is the native print export, not the browser view. Require: 1280×720 stages sized with % (never vw/vh); readable content ≥48px from all edges; inspect the exported PDF for clipped labels and footers.

Update instructions are a diff. “Make the hero darker and swap the CTA to Start free trial; keep everything else.” Do not resend the whole brief. Omit content unless copy actually changes. Keep the same format unless the user wants a different medium.

Example

User: “Make me a pitch deck for Loop, a B2B returns-logistics startup. Here are our notes…”

create_design {
  "name": "Loop pitch deck",
  "format": "pitch-deck",
  "instructions": "Seed-round pitch for logistics and e-commerce investors. 10–12 slides, one idea per slide, terse headlines, big numbers as callouts. Dark navy background, electric-green accent (#22C55E), Inter. Closing slide with contact: hello@loop.example.",
  "content": "# Loop\n\n## Problem\nReturns cost US retailers $743B in 2023...\n\n## Traction\n- 42 merchants\n- $1.2M ARR, +18% MoM\n..."
}

Tell the user job_id and run_id immediately, then wait_for_run once. If it is still running, offer email rather than polling again. A deck like this often takes 10–20 minutes. When complete, report viewer_url and offer export_design { format: "pdf" }.

Format selection

Export: pdf for print, slides, cards, certificates, resumes, invoices. html for landing-page, portfolio, link-in-bio, email-newsletter, dashboard. png when the user wants images (ZIP of PNGs).

Errors

Report to the user

After create (even while still generating): job_id and run_id. Do not invent or reuse a viewer_url. After a completed run (and again after export or publish): viewer_url from that run (it includes ?run=), job_id, run_id, status, charge_usd. After an edit, never paste the previous run's preview — wait until the new run is completed and use its viewer_url. After export: download_url. After a requested publish: public_url. Never invent URLs. Always persist and restate job_id and run_id — previews expire, IDs do not.