MCP

DocDealer speaks Model Context Protocol, so an AI agent can author templates and produce documents directly. One endpoint, two ways to authenticate, and the tool catalogue below.

The endpoint

Everything goes through a single JSON-RPC endpoint:

POST https://thedocdealer.com/mcp

The previous /api/mcp endpoint and its subpaths remain available as compatibility aliases, including OAuth and documentation URLs. Existing clients can keep their configured address; new connections should use /mcp. Both addresses serve requests directly, without redirects.

It is stateless: no session id, no resumability, no server-initiated streams. GET and DELETE return 405 by design.

Authenticating

{
  "mcpServers": {
    "docdealer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thedocdealer.com/mcp",
        "--header",
        "Authorization: Bearer dd_live_xxxxxxxxxxxx"
      ]
    }
  }
}

curl -X POST https://thedocdealer.com/mcp \
  -H "Authorization: Bearer $DOCDEALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools

84 tools, grouped by what you would reach for them to do.

One resource is exposed: docs://docdealer, a static overview of what the server does and which tool to call for what. Everything dynamic is a tool — most MCP clients never fetch a resource unless the user attaches it, so anything an agent must be able to reach on its own is a tool.

Guides

Workflows are served as task guides rather than baked into tool descriptions, so an agent pays only for the one it is doing:

• list_guides() lists every guide with when to use it.
• get_guide({ name }) returns one complete guide. orchestrator comes first and routes to the rest: generate-documents and form-data for drafting, author-templates, template-format and template-markup for template work, and manage-organization, manage-ai-profiles, design-word-formats, manage-connectors and manage-users for administration.
• get_template_generation_context({ templateId }) returns one template's form checklist, conditional keys, attachment and address fields, section ids and any agentInstructions its author wrote — replacing a separate get_template call.

Interactive sessions (OAuth or a user JWT) must read the whole guides a write depends on before calling it — for example orchestrator, generate-documents and form-data before create_document. A write called too early returns guide_required with the missing guide names; reading them and retrying is enough. Guide reads grant no permission. API-key sessions are integrations and are not gated.

Template work has one route with five guides — orchestrator, author-templates, template-format, template-markup and form-data — and the orchestrator lists all of them up front. Document tools aimed at a template's draft test document accept that authoring set in place of generate-documents.

whoami answers the other orientation question — who this credential belongs to, which organization is active, and which operations the session may actually perform. Its capabilities block is computed by calling the same checks the tools enforce, so it cannot disagree with them, and it saves an agent from discovering its own permissions by failing a write.

Two more tools support authoring: get_template_examples returns one validated snippet per construct of the template format, and list_section_tools lists the tokens a section's tools attribute may name — including this organization's connector tools, which cannot be guessed.

The authoring loop

export_template → edit → validate_template → test_template → import_template → create_template_version. The template format is strict: every rule is an error, checked on the form the editor stores, and validate_template also checks the organization's AI profiles, connector tools and Word formats. import_template, every update_template_* write and create_template_version refuse exactly what validate_template reports (code: "invalid"); there is no override, and generation refuses a stored template that breaks a rule.

test_template is free in its default rules mode. Its generate mode is metered — one AI call per requested section (sectionIds, or allSections: true), with form validation, document validation and title generation off unless asked — needs documents:generate and is rate-limited per organization. Scenario form data is validated strictly, like every other writer.

get_draft_test_document({ templateId, reset? }) returns the template's draft test document: one reusable document per template, generated from the current draft, never listed among real documents. Its documentId works with every document tool — form writes, attachment upload and analysis, generation, validation and DOCX/PDF export — so the full pipeline can be checked before publishing. It needs template-authoring permission. AI calls on the draft test document are not billed, so they are rate-limited per organization. delete_document removes a real document (the creator or an org admin; documents:delete for keys) and refuses the draft test document, which is reset instead. DELETE /api/documents/{id} applies exactly the same rules.

Clients also receive an instructions string at initialize, built per caller, naming the document types that credential can see. That reaches the model's system prompt without a tool call, so an agent recognises a request for one of your document types without asking first.

How authorization differs from REST

Worth understanding before you mint a key for an agent, because it is not what the REST rules would lead you to expect.

Tool reference

Every tool's input schema is published in the MCP OpenAPI document, which needs no credentials:

curl https://thedocdealer.com/mcp/openapi.public.json

Import a Word format from DOCX

Read design-word-formats, then call extract_word_format with the DOCX filename. Post the file directly to the returned signed uploadUrl; the response provides renderer configuration and normalization warnings. The upload expires after ten minutes and accepts at most 10 MiB. A 512 KiB inline base64 fallback is available for clients without direct upload support. The extracted configuration and preview inputs share an 8 MiB UTF-8 JSON budget, including embedded media; reduce oversized images before importing.

Extraction requires organization:write, saves nothing, and does not change the organization default. Preview the extracted configuration with representative HTML, inspect the PDF, then call create_word_format to save it. The parser bounds ZIP expansion, and extraction is limited to one concurrent job per organization and twenty jobs per ten minutes.