Integration guide · AI clients

Connect an AI assistant to your report workflow

Open Reports provides a local, single-file MCP server for Claude Desktop, Claude Code, Cursor, and other clients that support local stdio MCP servers. The assistant can inspect, validate, preview, edit, and render report definitions through your Open Reports API.

Set it up from the designer

1. Open Settings → AI tools (MCP) in the designer.
2. Download open-reports-mcp.mjs and save it somewhere permanent. It requires Node.js 18 or newer; the file contains no API key or server settings.
3. Select Claude Desktop, Claude Code, or Cursor in the setup panel, enter the file path, and copy the generated configuration into that client's MCP settings.
4. Set the API URL to your Open Reports server. Replace YOUR_API_KEY with a key configured for that server; if the server has no API keys, remove the REPORTS_API_KEY line.

The public demo serves the same download at /mcp/open-reports-mcp.mjs. You can also inspect its tool list at /api/v1/mcp.

Start in read-only mode

For a first session, enable Read-only in the setup panel. The generated config adds --read-only, which hides tools that save or publish templates, delete stored items, or write files.

{
  "mcpServers": {
    "open-reports": {
      "command": "node",
      "args": ["/full/path/open-reports-mcp.mjs", "--read-only"],
      "env": {
        "REPORTS_API_URL": "https://reports.example.com",
        "REPORTS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Use the configuration generated by the designer for the MCP client you use; the example above shows the shared JSON configuration shape. Keep keys out of source control and browser code.

Try a report with an AI client

Start with a built-in example and synthetic data. For example, ask the assistant to:

List the available example reports. Open the invoice example,
analyze its pagination, and preview every page. Do not save or publish anything.

The tools can explain report structure, validate and paginate a definition, show the rendered page text, and render outputs such as PDF, DOCX, XLSX, HTML, CSV, ZPL, or ESC/POS. An agent can propose changes with component-addressed JSON patches, so you can review the result instead of asking the model to calculate layout itself.

Use your own server for private reports

The shared demo is public. Use fictional data there; do not send patient, customer, financial, or other confidential records. For private work, self-host Open Reports, configure server API keys, and connect the local MCP process to that server. Your application should continue to authorize users, prepare only the data they may access, and select the report definition.

An MCP client may send tool results to its configured model provider. Review that provider's data-handling settings before using confidential reports. Read-only mode limits available actions; it does not make sensitive data safe to share.

Know the migration limits

The MCP tools can import JRXML files available to the local process and return review notes. Conversion is partial: imported reports are drafts that need review, and compiled .jasper files are not supported. Compare rendered output against the original before relying on a migration.

See the JasperReports comparison, JRXML import limits, and REST render guide.