docauto-mcp

DocAuto MCP server

A Model Context Protocol server that exposes the DocAuto document-generation workflow to AI assistants. It is a thin client over the public /api/v1 surface — it holds no secrets and enforces no business logic; multi-tenancy and validation live in the backend.

• Transport: stdio (local) and a hosted Streamable-HTTP server at https://mcp.docauto.com.br/mcp (add it as a remote connector — no install).
• Auth (local): OAuth 2.0 Device Authorization Grant against the Keycloak docauto-cli public client. You sign in once in your browser; tokens are cached at ~/.docauto/mcp-tokens.json (0600) and refreshed automatically.

Install

The server is a standalone Python package (it is not part of the backend). Requires Python ≥ 3.11.

# run on demand, no install:
uvx docauto-mcp
# or install it:
pipx install docauto-mcp

From a checkout (dev): pip install ./mcp.

Configure your MCP client

Claude Desktop — automatic

The package ships a setup helper that writes claude_desktop_config.json for you (handling the Windows Store/MSIX config-path quirk):

docauto-mcp-install            # register the installed `docauto-mcp` command
docauto-mcp-install --command uvx   # zero-install: run via `uvx docauto-mcp`
docauto-mcp-install --print    # print the JSON block instead of writing it

Claude Desktop — manual

{
  "mcpServers": {
    "docauto": {
      "command": "docauto-mcp"
    }
  }
}

If docauto-mcp is not on your PATH, use the uvx form ("command": "uvx", "args": ["docauto-mcp"]) or point command at the script inside your virtualenv.

Claude Code (CLI)

claude mcp add docauto -- uvx docauto-mcp

Cursor / VS Code / other clients

These accept a remote MCP server by URL — see the hosted server below (https://mcp.docauto.com.br/mcp), which needs no local install.

Environment overrides (optional)

Defaults target production; override only for local dev:

Variable	Default
DOCAUTO_MCP_ISSUER	https://auth.docauto.com.br/realms/docauto
DOCAUTO_MCP_API_BASE	https://api.docauto.com.br (server-to-server; set to the internal service in-cluster)
DOCAUTO_MCP_PUBLIC_API_BASE	https://api.docauto.com.br (public base for user-facing links, e.g. signed download URLs)
DOCAUTO_MCP_PUBLIC_APP_BASE	https://docauto.com.br (public frontend base for the upload page link)
DOCAUTO_MCP_CLIENT_ID	docauto-cli
DOCAUTO_MCP_HOME	~/.docauto (token cache location)

Logging in

You sign in with your normal DocAuto account (the MCP server does not create a different kind of account):

• Call login_start — it returns a verification URL and a short code.
• Open the URL, sign in (email/password or Google), and approve.
• Call login_finish — it completes the login and caches your tokens.

After that the assistant can use the tools below; tokens refresh silently until the session expires.

Prompts

• generate_documents (argument: output_format = pdf | docx) — a guided template that drives the whole batch-generation flow. Available in any client that surfaces MCP prompts, over both transports.

Tools

• Session: login_start, login_finish, logout, whoami, doctor, workflow_guide — doctor reports the version, the configured endpoints, API reachability, and sign-in state (no secrets)
• Templates: list_templates, get_template, upload_template, delete_template
• Datasets: list_datasets, get_dataset, preview_dataset, upload_dataset, delete_dataset
• Generation: validate_mapping, create_generation_job, get_job, list_jobs, cancel_job, delete_job, list_job_documents
• Conversions (standalone DOCX→PDF): convert_docx_to_pdf, get_conversion, list_conversions, download_conversion, delete_conversion — converts one document with no template, dataset or mapping. Over stdio convert_docx_to_pdf(path) reads a local file and download_conversion saves the PDF to Downloads; over the hosted transport convert_docx_to_pdf(filename) returns an upload_url (poll check_upload) and download_conversion returns the PDF inline, since a conversion's input is capped at 10 MB
• Downloads: download_document, download_job_zip — over stdio these save to the user's local Downloads folder; over the hosted HTTP transport download_job_zip returns a short-lived signed URL the user opens in a browser (the ZIP is never streamed through the model, so there is no size cap)
• Uploads (hosted HTTP only): over stdio upload_template/upload_dataset read a local path; over the hosted transport they take only a filename and return an upload_url the user opens to send the file (the bytes never pass through the model), plus an upload_ref to poll with check_upload until the result is ready

Typical flow

login_start → login_finish → whoami → upload_template(path) → upload_dataset(path) → validate_mapping(...) → create_generation_job(...) → poll get_job(job_id) → download_job_zip(job_id, dest).

The field_mapping maps each template variable to a dataset column, e.g. {"nome_cliente": "nome_cliente", "cpf": "cpf"}. output_format is pdf (default) or docx.

Just need one document as a PDF? Skip all of that: convert_docx_to_pdf(path) → poll get_conversion(id) → download_conversion(id).

Development

# unit tests (no MCP SDK needed — auth/client/tools are isolated)
python -m pytest tests