Skip to main content

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 Report Flow PDFs from natural language.

Why Report Flow MCP?​

Several MCP servers exist for business-document generation, but Report 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. The security posture matches Claude.ai's first-party Connectors.

What it does​

  • Generate PDFs from natural-language requests like "create an invoice for Acme Corp totalling $330"
  • Expose your Report 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 Report 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 Report Flow account and an AI client that supports remote MCP servers.

Setup​

There are two ways to set up. Local execution (npx) is recommended, and it can save generated PDFs into your local workspace folder. If you'd rather not install Node.js, or you're using a browser-based client such as Claude.ai (web), use the remote (hosted) server.

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.

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).

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.

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. Slash commands (prompt templates)​

CommandPurpose
/generate_pdfStep-by-step recipe for a single PDF
/generate_pdfsRecipe for batch PDF generation
/reportflow_helpQuick feature tour

3. 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)​

ToolPurpose
authenticateFirst-time / re-authentication
list_templatesList available designs
get_design_parametersFetch the parameter schema for a design
generate_pdf_sync / generate_pdf_asyncGenerate one PDF (sync returns a path; async returns a request ID)
generate_pdfs_sync / generate_pdfs_asyncGenerate many PDFs (returns a ZIP)
download_file / download_zipDownload artifacts produced by async tools
suggest_paramsTranslate a natural-language brief into a params JSON via MCP Sampling (requires a Sampling-capable client)

Resources (attachable as AI context)​

URIContents
reportflow://designsList of available designs
reportflow://designs/{designId}/parametersParameter schema for one design
reportflow://errorsCatalog of error messages from the Content Service
reportflow://server-infoServer feature overview

Prompts​

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

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

Troubleshooting​

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​

Next steps​