Re:port Flow MCP

Re:port Flow MCP

[npm version] [License: MIT]

Official display name: Re:port Flow MCP. Package and implementation identifier: reportflow-mcp. Legacy search aliases: ReportFlow MCP Server and ReportFlow.

Overview

An MCP (Model Context Protocol) server that turns your Re:port Flow templates into PDF reports — invoices, contracts, statements, anything you've designed — straight from Claude or any other MCP-compatible AI agent.

Features

• Generate PDFs from natural-language requests like "create an invoice for Acme Corp totalling $300"
• Expose your Re:port Flow designs and their parameter schemas directly to the AI as MCP Resources
• Bulk-generate many PDFs and download them as a single ZIP
• Save outputs to whichever workspace folder the user is currently in (Claude Desktop / Claude Code / Cursor / VS Code all supported)

Agent Skill

Agents that should follow a procedure (not just read the protocol) use skills/re-port-flow/SKILL.md. Copy that directory into Claude Code / Codex .agents/skills or a Cursor project skill folder. PDF generation always goes to https://mcp.re-port-flow.com/mcp. The Hugging Face Space MCP (org card) is gallery-only — add it from the Space MCP badge → Add to MCP tools, not as a substitute for the product endpoint.

Setup

Re:port Flow MCP runs in two ways — pick whichever matches your client.

Remote server (claude.ai / web clients) — Streamable HTTP

Add Re:port Flow as a custom connector pointing at the hosted endpoint:

https://mcp.re-port-flow.com/mcp

In Claude (claude.ai) go to Settings → Connectors → Add custom connector and paste the URL above. Authentication is handled in-app via OAuth (see Authentication) — nothing to install locally.

Local server (Claude Desktop / Claude Code / Cursor) — stdio via npx

Add the following to your config file (.mcp.json, claude_desktop_config.json, ~/.cursor/mcp.json, etc.):

{  "mcpServers": {    "reportflow": {      "command": "npx",      "args": ["-y", "reportflow-mcp"]    }  }}

That's the whole setup. No env vars, no API keys, no secrets to manage.

VS Code (MCP-enabled builds)

Same JSON in .vscode/mcp.json.

Requirements

• Remote: an MCP client that supports custom HTTP connectors (e.g. claude.ai). No local install.
• Local (stdio): Node.js 22.23.4 or later in the 22.x line (engines: ^22.23.4) and a browser available during the first login. Install a patched Node.js separately; npx downloads the MCP package. The minimum patch requirement includes the 2026-10-21 Node.js security fixes.
• A Re:port Flow account (either way).

Supported protocol revisions

Both transports (stdio / Streamable HTTP) serve two MCP protocol generations from a single endpoint:

• 2026-07-28 (current) — stateless per-request protocol. Modern clients discover it via server/discover; no session header, requests carry their protocol version in _meta.
• 2025-era revisions (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07) — classic initialize handshake, kept for backwards compatibility with existing clients (Claude Desktop, claude.ai custom connectors, Cursor, ChatGPT, n8n, …).

Version selection is automatic on both transports: modern clients probe with server/discover, legacy clients keep sending initialize — no configuration is required on either side, and existing connections keep working unchanged.

Either handshake also returns MCP instructions: a short brief telling the connected AI what Re:port Flow does and how to reach a first PDF (gallery search → copy → parameters → generate), so it can offer to create a document right after you connect instead of waiting to be asked. How closely a client follows those instructions is up to that client.

A2A (Agent2Agent)

The remote server also speaks A2A v1.0 over the JSON-RPC binding:

• Agent Card: https://mcp.re-port-flow.com/.well-known/agent-card.json
• Endpoint: POST https://mcp.re-port-flow.com/a2a (SendMessage)

Each A2A skill is one of the MCP tools above (the skill id is the tool name). Send a message with a data part {"skill": "<tool name>", "arguments": {...}}; the arguments follow that tool's input schema, and the call runs through the same authorization and workspace permissions as MCP. Authorize with the same OAuth flow (the MCP access token works as-is). Streaming, push notifications and task retrieval are not supported: every SendMessage returns a finished task.

Authentication

Remote (claude.ai)

When you add the connector, Claude runs the OAuth flow for you: Sign in → pick a workspace → consent. Tokens are held by the client — there's no local keychain or browser step to manage.

Local (stdio)

After reloading the MCP client, ask the AI:

Authenticate with Re:port Flow

A browser window opens. Sign in → pick a workspace → consent, and you're done. Tokens are stored in your OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), with a chmod-0600 file fallback, and are refreshed automatically.

Usage examples

Each example below is a prompt you can paste as-is; the AI picks the right tools.

1. Generate a single PDF (list → schema → generate)

Using the invoice template, create a PDF for Acme Corp totalling $330.

The AI lists designs with list_templates, fetches the parameter schema with get_design_parameters, fills in the values, and calls generate_pdf_sync.

• Remote: returns fileUrl — the output-history page of the Re:port Flow web app (sign-in required). It is not a direct file download link.
• Synchronous generation times out after 60 seconds (the API returns 504); use generate_pdfs_async for anything that may take longer.
• Local: also saves the file and returns its absolute path.

2. Batch-generate many PDFs

From the statement template, generate one PDF per customer (Acme $100, Globex $250, Initech $80) and give them to me together.

• Local (stdio): generate_pdfs_sync writes a single ZIP to your workspace.
• Remote: generate_pdfs_async runs the batch and returns a request id plus the output-history page URL (url). get_generation_status tells you when the batch has finished or failed.

3. Async generate, then download (local)

Kick off the contract PDF in the background, then download it once it's ready.

The AI calls generate_pdf_async (returns a requestId immediately), checks progress with get_generation_status, then calls download_file to save the finished PDF. The batch equivalent is generate_pdfs_async → download_zip. If a download is attempted while the file is still being generated, the tool reports FILE_NOT_READY with the number of seconds to wait instead of failing. These download tools are stdio-only; on the remote server the sync/async tools return the output-history page URL instead.

requestId, fileId and designId are short alphanumeric strings (for example 0eUDdgAjNXrrItA2), not UUIDs.

Tip — natural-language params: on a Sampling-capable client you can ask "draft the params for a $1,000 invoice to A社" and the AI will call suggest_params to turn the brief into a valid params object before generating.

4. Start from zero templates (gallery → copy → generate)

I don't have any templates yet — create an invoice PDF for Acme Corp.

When list_templates is empty, the AI searches the public template gallery with search_gallery_templates, shows you the candidates, copies your pick into your workspace with copy_gallery_template, and then proceeds with the normal flow (get_design_parameters → generate_pdf_sync). The copy always lands in the workspace you selected on the OAuth consent screen — the AI cannot target any other workspace.

If the search finds nothing, the result carries a templateSite link to the template gallery site, where you can browse the designs. Share the page URL of the one you like (/templates/{slug}) and the AI copies it by that slug.

Slash commands

Where files are saved (local mode)

Output location is resolved in this order:

1. Explicit instruction from the user (e.g. "save to my Desktop")
2. The currently-open workspace root (Claude Code / Cursor / VS Code)
3. The OS temp directory as fallback

Build your own agent

The setup above assumes an MCP client that manages its own connection and login. If you are writing the agent yourself — Hugging Face Agents, a custom tool loop, or raw HTTP — the hosted endpoint is open to you directly:

https://mcp.re-port-flow.com/mcp

• agents.md — the agent-facing guide: transport details, the ten HTTP tools, the OAuth flow, model selection, and the rules an agent has to follow (never invent business data; copy_gallery_template is not idempotent; passthrough values end up in the PDF's metadata).
• examples/ — runnable Python, JavaScript and curl clients, plus a script that walks the OAuth flow and prints an access token.

initialize and tools/list work without credentials, so you can discover the toolset before wiring up authentication. Every tools/call needs a Bearer token.

Hugging Face

Re:port Flow is on the Hub at huggingface.co/reportflow. The Hugging Face SDKs have no MCP OAuth flow of their own, so fetch a token once with examples/oauth/get-token.sh and inject it as an Authorization header — see examples/python/hf_mcp_client.py and examples/javascript/hf-mcp-client.mjs.

Reference

Tools (called by the AI)

Resources (attachable as AI context)

Prompts (slash-command recipe cards)

/generate_pdf, /generate_pdfs, /reportflow_help — pass arguments and the AI follows the prepared workflow.

Troubleshooting

Privacy

Re:port Flow MCP is a thin client: it forwards your requests to your own Re:port Flow account and returns the generated PDFs. It does not sell or share your data with third parties. Authentication tokens are stored locally (OS keychain, or a chmod-0600 file fallback) and are sent only to Re:port Flow's own services — during the OAuth login, and as a Bearer credential on each authenticated API call (listing templates, generating or downloading PDFs). They are never shared with any third party.

For the full privacy policy — what is collected, how long it is retained, and how it is handled — see: lp.re-port-flow.com

Security

The hosted endpoint validates the Host header (DNS-rebinding protection) and rejects structurally invalid Origin headers with 403 Forbidden, per the MCP Streamable HTTP specification's Security requirements. Authentication is Bearer-token only — no cookies, and CORS never allows credentials. The full policy and its threat model are documented in docs/security.md (Japanese).

Support

Need help, found a bug, or have a directory-review question?

• Re:port Flow (privacy & support): https://lp.re-port-flow.com
• GitHub Issues: https://github.com/re-port-flow/reportflow-mcp/issues

License

MIT — see LICENSE.

Links

• Re:port Flow: https://re-port-flow.com
• Privacy & Support: https://lp.re-port-flow.com
• npm: https://www.npmjs.com/package/reportflow-mcp
• Hugging Face: https://huggingface.co/reportflow
• Agent guide: agents.md
• Examples: examples/
• Issues: https://github.com/re-port-flow/reportflow-mcp/issues