MCP Server (Claude / Cursor / VS Code)

We provide an official Model Context Protocol (MCP) server, reportflow-mcp, that lets any MCP-compatible AI client — Claude Desktop, Claude Code, Cursor, VS Code, and more — generate Re:port Flow PDFs from natural language.

• Hosted endpoint (no npm required): https://mcp.re-port-flow.com/mcp
• Claude connector directory: listed as Re:port Flow under Directory → Connectors in the Claude app (community connector)
• npm: reportflow-mcp
• Source: github.com/re-port-flow/reportflow-mcp
• MCP Registry: io.github.re-port-flow/reportflow-mcp

Why Re:port Flow MCP?

Several MCP servers exist for business-document generation, but Re:port Flow MCP differentiates itself on three axes.

1. Remote-ready, setup-free — A hosted endpoint at https://mcp.re-port-flow.com/mcp lets you connect from Claude.ai (web) without installing npm or Node.js. Unlike other Japanese 帳票 (chohyo) MCP servers that ship as stdio-only local processes, business users without a dev environment can start using it day one.
2. No-code template design + template marketplace — Templates are designed in a browser-based GUI editor (Konva-based) with no code. A free template gallery covers invoices, quotes, receipts, delivery slips, reports and more, so AI agents can invoke ready-made templates from day one. You don't need to author JSON schemas to add templates.
3. OAuth 2.0 + dynamic client registration — Authentication is OAuth 2.0 (Authorization Code + PKCE) with Dynamic Client Registration — no API key is ever handed to the AI client. Local-mode tokens live in the OS keychain; remote-mode tokens are managed server-side. Every scope requested is documented under OAuth and scopes.

What it does

• Generate PDFs from natural-language requests like "create an invoice for Acme Corp totalling $330"
• Even with zero templates, search the public template gallery, copy a template into your workspace, and go all the way to PDF generation
• Expose your Re:port Flow designs and their parameter schemas to the AI as MCP Resources
• Bulk-generate many PDFs and download them as a single ZIP
• Save outputs to whichever workspace folder the AI client is currently in

Requirements

• Node.js 18+ (auto-fetched by npx)
• A local environment with a browser (only for the first login)
• A Re:port Flow account

These are the requirements for local execution (npx). With the remote (hosted) server, you don't need Node.js or a local browser/keychain — all you need is a Re:port Flow account and an AI client that supports remote MCP servers.

Setup

There are three ways to connect. Pick the one that matches your use case.

Method	Best for	How you receive output
Add from the connector directory	You use Claude and don't want to edit config files	Download URL
Remote (hosted) server	Non-Claude remote-MCP clients, or specifying the URL yourself	Download URL
Local execution (npx)	You want generated PDFs saved into your local workspace folder	Local file path

Choose local execution (npx) only if you need files written to disk automatically. Otherwise a remote connection is enough, and it needs no Node.js.

Add from the Claude connector directory (fastest)

reportflow-mcp is listed in Claude's connector directory. If you use Claude, you can add it from there without typing the endpoint URL.

1. Open Claude and go to Settings → Connectors (or the in-app Directory)
2. Select the Connectors tab and type Re:port Flow into the search box
3. Pick Re:port Flow from the list and press Add / Connect
4. An OAuth consent screen opens in your browser: sign in → pick a workspace → approve

Once connected, you can ask directly: "Using the invoice template, create a PDF for Acme Corp totalling $330." See OAuth and scopes for the permissions requested.

About the directory listing

The directory shows the connector as Re:port Flow, categorised as a community connector. The listing does not imply any certification or partnership beyond that.

If you can't find it in the directory, or you use a client other than Claude, register the URL directly using either of the two methods below.

Local execution (npx, recommended)

Claude Desktop / Claude Code / Cursor

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 entire setup. No env vars, no API keys, no secrets to manage on the client — authentication uses OAuth.

VS Code (MCP-enabled builds)

VS Code uses a top-level servers key (different from Claude / Cursor's mcpServers). Add the following to .vscode/mcp.json:

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

Remote (hosted) server

No npm or Node.js installation required — you connect to a hosted endpoint by URL. This suits Claude.ai (web) and any client that supports remote MCP servers. Authentication runs as OAuth (Dynamic Client Registration) in the client's browser, and tokens are managed server-side, so no local keychain is used.

Endpoint:

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

For clients that support the HTTP transport (Claude Code, Cursor, etc.), add the following to your config file:

{
  "mcpServers": {
    "reportflow": {
      "type": "http",
      "url": "https://mcp.re-port-flow.com/mcp"
    }
  }
}

In VS Code (.vscode/mcp.json), the top-level key is servers:

{
  "servers": {
    "reportflow": {
      "type": "http",
      "url": "https://mcp.re-port-flow.com/mcp"
    }
  }
}

With the Claude Code CLI you can also add it with:

claude mcp add --transport http reportflow https://mcp.re-port-flow.com/mcp

In Claude.ai (web / desktop), register the URL above under Settings → Connectors (custom connector). An OAuth consent screen opens in your browser on connect. If you use Claude, you can skip typing the URL and add it from the connector directory instead.

Difference from local execution

The remote server can't access your file system, so generated PDFs are not saved to a local workspace folder — they're returned as download URLs instead. If you want generated files saved locally and automatically, use local execution (npx).

Supported protocol revisions

Both transports (local stdio and remote Streamable HTTP) serve multiple MCP protocol revisions from a single endpoint.

• 2026-07-28 (current) — a stateless protocol. Modern clients discover the server via server/discover; there's no session header, and each request carries its protocol version in _meta.
• 2025-era and earlier revisions (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07) — the classic initialize handshake, kept for backwards compatibility with existing clients (Claude Desktop, Claude.ai custom connectors, Cursor, ChatGPT, n8n, and others).

Which revision a connection uses is negotiated automatically — there's nothing for you to configure. Modern clients probe with server/discover, and legacy clients keep sending initialize. The setup and configuration steps described on this page don't change either way.

First-run authentication

After reloading the MCP client, ask the AI:

Authenticate with ReportFlow

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) and refreshed automatically.

When the keychain isn't available

On Linux without libsecret, the server automatically falls back to a chmod-0600 file under $XDG_STATE_HOME/reportflow-mcp/.

For the remote (hosted) server

The steps above apply to local execution (npx). With the remote server, the OAuth consent flow starts automatically when the client connects, and tokens are managed server-side. There's no need to ask the AI to "log in" and no local keychain is involved.

OAuth and scopes

The remote (hosted) endpoint is protected by OAuth 2.0 (Authorization Code + PKCE). Client registration happens automatically via Dynamic Client Registration (RFC 7591), so there is no API key or client secret to configure on the Claude side.

The consent screen requests these scopes:

Scope	Purpose
openid / profile	Identify the signed-in user
designs:read / designs:write	Read and update designs
templates:read / templates:write	Read and update templates
pdf:generate	Generate PDFs

See OAuth 2.0 authentication for the full definition of each scope — the MCP server uses the same authorization server.

The authorization code flow requires PKCE (S256), and the token endpoint uses none authentication (public client). Access tokens are refreshed automatically via refresh_token.

The server publishes the following discovery documents. They are the fastest way to triage a failing connection:

Endpoint	Spec	Contents
/.well-known/oauth-protected-resource	RFC 9728	Protected-resource metadata (authorization server location, scope list)
/.well-known/oauth-authorization-server	RFC 8414	Authorization-server metadata (/authorize, /token, /register)
/healthz	—	Health check; returns {"status":"ok"}

curl -s https://mcp.re-port-flow.com/healthz
curl -s https://mcp.re-port-flow.com/.well-known/oauth-protected-resource
curl -s https://mcp.re-port-flow.com/.well-known/oauth-authorization-server

Usage

1. Generate a PDF from natural language

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

Behind the scenes the AI will:

1. Look up your designs via list_templates
2. Fetch the parameter schema with get_design_parameters
3. Build a params object from your request
4. Call generate_pdf_sync and return the local file path

2. Start from zero templates (gallery search → copy → generate)

I want an invoice PDF, but I don't have any templates yet.

When the workspace has no designs, the AI finds a candidate in the public template gallery, copies it, and joins the normal generation flow:

1. search_gallery_templates searches the gallery and presents candidates (no auth needed)
2. Optionally get_gallery_template shows full details (description, copy count)
3. copy_gallery_template copies your pick into your workspace
4. The returned designId / version feed get_design_parameters → generate_pdf_sync

The copy always lands in the workspace you selected on the OAuth consent screen — the target cannot be changed via tool arguments. Note that copy_gallery_template creates a new design on every call (it never reuses a previous copy).

3. Slash commands (prompt templates)

Command	Purpose
/generate_pdf	Step-by-step recipe for a single PDF
/generate_pdfs	Recipe for batch PDF generation
/reportflow_help	Quick feature tour

4. Where files are saved

Output location is resolved in this order:

1. An 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

Reference

Tools (called by the AI)

Tool	Purpose
authenticate	First-time / re-authentication
list_templates	List available designs
get_design_parameters	Fetch the parameter schema for a design
search / fetch	Resolve designs in your workspace by partial name match (search; omit the query to list everything), then fetch one design's parameter schema by the returned <designId>@<version> id (fetch). This is the search / fetch tool pair some clients require. Neither performs a web search or reaches any external site — both are scoped to your workspace
generate_pdf_sync / generate_pdf_async	Generate one PDF (sync returns a path; async returns a request ID)
generate_pdfs_sync / generate_pdfs_async	Generate many PDFs (returns a ZIP)
download_file / download_zip	Download artifacts produced by async tools
suggest_params	Translate a natural-language brief into a params JSON via MCP Sampling (requires a Sampling-capable client)
search_gallery_templates	Keyword search over the public template gallery (no auth needed). The returned slug cannot generate PDFs until the template is copied
get_gallery_template	Fetch one gallery template's details by slug (no auth needed)
copy_gallery_template	Copy a gallery template into your authorized workspace (write). The target workspace is fixed by the access token and cannot be passed as an argument. Returns designId / version ready for get_design_parameters → generate_pdf_sync

Resources (attachable as AI context)

URI	Contents
reportflow://designs	List of available designs
reportflow://designs/{designId}/parameters	Parameter schema for one design
reportflow://errors	Catalog of error messages from the Content Service
reportflow://server-info	Server feature overview

Prompts

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

Related endpoints

The MCP server calls the Re:port Flow API under the hood. For the underlying contracts, see:

• Single PDF Sync Generation
• Single PDF Async Generation
• Multiple PDF Sync Generation
• Multiple PDF Async Generation
• File Download
• Design Parameters

Troubleshooting

First determine whether the symptom occurs on a remote connection (connector directory / custom connector) or on local execution (npx).

"Re:port Flow" doesn't appear in the Claude directory

Directory contents can differ by client type, version, and rollout state. If you can't find it, register the URL directly as a custom connector via Remote (hosted) server — it connects to the same server.

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

The OAuth consent screen doesn't open, or fails partway

Start by checking that the server itself is up:

curl -s https://mcp.re-port-flow.com/healthz
curl -s https://mcp.re-port-flow.com/.well-known/oauth-protected-resource

If healthz returns {"status":"ok"} and the discovery document returns JSON, the server side is healthy. In that case check:

• Whether a browser popup blocker or tracking-prevention feature is blocking the consent window
• Whether your corporate proxy / firewall allows HTTPS traffic to mcp.re-port-flow.com
• Whether you selected the intended workspace on the consent screen

401 Unauthorized

The protected call carried no valid access token. The WWW-Authenticate response header names the authorization server needed to re-authenticate. Remove the connector in Claude, reconnect, and complete the OAuth consent again.

It connects, but no templates are listed

list_templates only returns designs from the workspace you authorized. You may have picked a different workspace on the consent screen — reconnect the connector and select the intended one. If the workspace has no designs yet, ask the AI to "find an invoice template" — it will search the public template gallery with search_gallery_templates and copy your pick into the workspace with copy_gallery_template (you can also create a design from scratch in the Re:port Flow console).

PDFs aren't saved locally on a remote connection

That's the expected behaviour. The remote server can't reach your file system, so artifacts are returned as download URLs. To have files written into your local workspace folder, use local execution (npx).

Errors containing re-authentication required

Your tokens have expired. Ask the AI: "re-authenticate with ReportFlow".

npx cannot find the package

npm cache clean --force

then retry.

No keychain available on Linux

If libsecret is missing, the server automatically falls back to a chmod-0600 file under $XDG_STATE_HOME/reportflow-mcp/.

Browser cannot open over SSH / remote shell

Authenticate once on a local machine. After the initial login, the cached token can be reused on remote hosts — either via the same OS keychain entry, or by copying the fallback file mentioned above.

Rate limit exceeded (429)

Per-workspace rate limit. Wait the number of seconds reported in the Retry-After header before retrying. For batch jobs, prefer the async endpoints.

Support

• Bugs / feature requests: GitHub Issues
• General API questions: Re:port Flow API documentation

Next steps

• Async Workflows — bulk-generation best practices
• Webhook Notifications — completion events and HMAC-SHA256 verification
• n8n integration — low-code workflow integration