---
title: "@quario/mcp — API reference"
description: "Reference for the quario MCP server, covering its environment variables, its two tools and the shapes they return."
url: "https://getquario.com/docs/reference/mcp"
---

# @quario/mcp

An MCP server that exposes quario as two tools. It runs locally over stdio, and
`npx @quario/mcp` starts it. The package carries the engine and the five render
targets as dependencies, and needs Node 22 or later.

## Configuration

The server reads its configuration from environment variables. There are no
flags and no config file. An empty variable counts as unset.

| Variable | Sets | When unset |
| --- | --- | --- |
| `QUARIO_LICENSE` | the license key | unlicensed, and the output carries the watermark |
| `QUARIO_LOCALE` | the default `locale` | `en-US` |
| `QUARIO_CURRENCY` | the default `currency` | none |
| `QUARIO_TIME_ZONE` | the default `timeZone` | `UTC` |
| `QUARIO_SCHEMES` | the `href` schemes, comma-separated | `https:,mailto:` |
| `QUARIO_MAX_DEPTH` | a query budget, or `Infinity` | `500` |
| `QUARIO_MAX_NODES` | a query budget, or `Infinity` | unbounded |
| `QUARIO_MAX_RESULTS` | a query budget, or `Infinity` | unbounded |
| `QUARIO_DATA_ROOT` | the directory `dataPath` and `$image` resolve in | `CLAUDE_PROJECT_DIR`, else `dataPath` fails |
| `QUARIO_OUT_DIR` | the directory the server writes to | `quario-mcp` under the system temp directory |

A value the server can’t run with stops it at startup, and the message goes to
`stderr`. That covers a budget that doesn’t parse and a scheme the engine
refuses. It also covers a data root that doesn’t exist, and an output directory
the server can’t create or write. A license key that fails verification is
the one exception. The server starts, and the output carries the watermark.

## `validate_report`

Reads a definition for problems without rendering it.

| Field | Type | Notes |
| --- | --- | --- |
| `definition` | object | Required. |
| `targets` | array of `"html"`, `"pdf"`, `"xlsx"`, `"docx"`, `"csv"` | Optional. Checks `required` against each target. |

The `definition` field carries the full JSON Schema of the report document,
descriptions included. The server reads the call against that schema and passes
the definition to the engine unchecked. A fault comes back as one problem at the
path it sits at.

A problem is a successful result, never an error. The result carries
`structuredContent` with `{ problems, warnings }`, and one text block holding
the same object as JSON.

```ts title="result"
type Problem = {
  path: string
  source?: string
  message: string
  code?: string
  start?: number
  end?: number
}

type Warning = { path: string; message: string }
```

`code`, `start` and `end` come from the located diagnostic when the engine has
one.

## `render_report`

Renders a definition to one target and writes the output to a file.

| Field | Type | Notes |
| --- | --- | --- |
| `definition` | object | Required. |
| `target` | `"html"`, `"pdf"`, `"xlsx"`, `"docx"` or `"csv"` | Required. |
| `data` | any JSON value | Give exactly one of `data` and `dataPath`. |
| `dataPath` | string | A JSON file inside the data root. |
| `params` | object | Optional. Values for the definition’s `params`. |
| `locale` | string | Optional. Overrides `QUARIO_LOCALE` for this call. |
| `currency` | string | Optional. Overrides `QUARIO_CURRENCY` for this call. |
| `timeZone` | string | Optional. Overrides `QUARIO_TIME_ZONE` for this call. |
| `filename` | string | Optional. A file name without a directory. |
| `options` | object | Optional. `page`, `meta`, and `filter` for `xlsx`. |

The tool plans the definition against its target, so a `required` declaration
that target loses is a problem. A definition with problems returns the same
`{ problems, warnings }` as `validate_report`, marked `isError`.

`options` passes to the target factory. The server refuses `fonts` and `paths`,
and an unknown key returns the factory’s own message as an error. The `csv`
target takes no options.

**Render data.** Give exactly one of `data` and `dataPath`. `dataPath`
resolves inside the data root, tested after symlinks resolve, and without a
data root the server refuses it. A file that doesn’t parse returns the
server’s own message, never the file’s text. An image arrives as
`{ "$image": "<path>" }` or `{ "$base64": "…" }`, and either decodes to bytes
before the render at any depth. An `$image` path resolves inside the data root,
inside a `dataPath` file too, and names a PNG or JPEG. Without a data root the
server refuses it, and a refusal names its place in the data, such as
`$.input.logo`.

**The output file.** Every target writes a file to `QUARIO_OUT_DIR` and
returns its location, never its content. `filename` holds no separator and
isn’t `..`, and the server forces the target’s extension. Without one the name
is `report-<timestamp>.<ext>`. The server never overwrites: a name that exists
gets `-1`, then `-2`.

```ts title="result"
type Rendered = { path: string; target: string; bytes: number }
```

The text block reads `Wrote <name> (<size>): <absolute path>`.

## Not in this release

Registered functions, host fonts, and remote transport.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://getquario.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://getquario.com/docs"},{"@type":"ListItem","position":3,"name":"@quario/mcp","item":"https://getquario.com/docs/reference/mcp"}]}
```