> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/manual/organisation/built-in-mcp-servers/reports-mcp-server.md). # Reports MCP Server The **Reports MCP Server** is a built-in server that gives your AI agents the ability to create, build, and manage structured reports. Using this server, an agent can create a new report, populate it with a variety of content blocks (text, charts, tables, metrics, and more), edit existing reports, and advance a report through the review and publication workflow - all without leaving the conversation. The server also provides utility tools for date handling, arithmetic, and data aggregation that agents use to process raw data before presenting it in a report. ## Connection Parameters | **Parameter** | **Value** | | ------------------ | ----------------------------------------------------- | | **Server address** | `internal://reports` | | **Server type** | Internal (built-in, no external credentials required) | ## Key Concepts ### Reports and Blocks A report is a structured document made up of **blocks** placed in order. Each block has a type - a heading, a paragraph of text, a chart, a data table, and so on. The agent builds a report by creating it first (obtaining a report ID), then appending blocks one by one with `add_block`. Every block is assigned a unique **block ID** by the server when it is added. This ID is used to update or delete that specific block later. ### Block Types | **Block type** | **What it renders** | | --------------- | --------------------------------------------------------------------------- | | **Header** | A section heading (levels 1–6, like H1–H6) | | **Markdown** | Free-form formatted text (bold, lists, links, etc.) | | **Metric** | A single highlighted KPI value with a unit and description | | **Bar Chart** | A bar chart with labelled categories and values | | **Line Chart** | A line chart with one or more named series over time | | **Pie Chart** | A pie chart showing proportions across categories | | **Data Table** | A table with named columns and rows of data | | **Action Item** | A list of action items, each with a status, optional assignee, and due date | | **Image** | An image displayed by URL, at a chosen size | | **Columns** | A multi-column layout that holds other blocks side by side | ### Report Status Workflow Every report moves through a review lifecycle. Status changes can be made by the agent via the `update_report_metadata` tool. ``` DRAFT ──► IN_REVIEW ──► PUBLISHED ▲ │ │ └──────────────┘ │ ◄───────────────────────────────┘ ``` | Status | Meaning | | ----------- | --------------------------------------------------------- | | `DRAFT` | Being authored; not yet submitted for review. | | `IN_REVIEW` | Submitted and awaiting human approval before publication. | | `PUBLISHED` | Approved and publicly visible. | Allowed transitions: DRAFT → IN\_REVIEW, IN\_REVIEW → PUBLISHED, IN\_REVIEW → DRAFT, PUBLISHED → IN\_REVIEW, PUBLISHED → DRAFT. ## Available Tools ### Report Lifecycle | **Tool** | **Description** | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create_report` | Create a new empty report and save it to the database. Returns the report ID used by all subsequent tools. This is always the first step in a report-generation workflow. The initial status defaults to `DRAFT`. | | `update_report_metadata` | Update the title, summary, and/or status of an existing report. Only the fields you provide are changed - omitted fields remain as they are. Use this to rename a report, add a summary, or advance it to `IN_REVIEW` or `PUBLISHED`. | | `get_report_url` | Return the direct link to a report in the platform UI. Useful for sharing the report with a user at the end of a conversation. | ### Searching and Retrieving Reports | **Tool** | **Description** | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_reports` | Find existing reports by any combination of title text, author, generating agent, status, and creation date range - all filters are optional and combine with AND. Omit all filters to browse the most recently created reports. Returns each matching report's metadata (not its blocks), plus the total count across all pages. | | `get_report` | Return metadata for a single existing report - its title, summary, status, author, generating agent, and timestamps. Use this to read a report's summary or conclusions, e.g. before combining it with other reports. Does not return the report's blocks - use `get_report_blocks` for the full content. | ### Building Report Content | **Tool** | **Description** | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_report_blocks` | Retrieve all current blocks in a report, each with its block ID and full content. Always call this before editing an existing report so you know what is already there and can reference the correct block IDs. | | `add_block` | Append a new block to an existing report. The server assigns the block ID automatically. Blocks are added to the end of the report by default, or as a new column inside an existing `columns` block when a parent block ID is provided. | | `update_block` | Replace an existing block in full, addressed by its block ID. The block keeps its original ID after the replacement. Use this to correct or improve a block you have already added. | | `delete_block` | Remove a block from a report, addressed by its block ID. Works for blocks at the top level and for blocks nested inside a `columns` block. | ### Data and Calculation Utilities | **Tool** | **Description** | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `calculate` | Evaluate a mathematical expression and return the numeric result. Supports standard arithmetic operators and common functions (`round`, `sqrt`, `log`, `abs`, etc.). Use this to compute derived values - totals, averages, percentages - before placing them in a `metric` or `markdown` block. | | `get_date_range` | Return ISO 8601 start and end timestamps for a time window. Accepts either a named period (`today`, `last_7_days`, `last_month`, `this_year`, etc.) or an arbitrary number of days back from now. Call this first whenever a report request mentions a time window, so the correct dates are passed to any external data source. | | `aggregate_data` | Aggregate a set of data rows in memory - grouping, summing, averaging, counting, or finding min/max values - without hitting any database. Use this to process raw records returned by an external data source (a CRM, analytics API, etc.) before visualising the results in a chart or table block. |