# MCP tools

Every tool of the MCP server, written from its own definitions. [Connect an assistant](https://docs.ocost.io/en/mcp.md) sets the server up. An assistant reads each tool's full description in `tools/list`.

## `documents:read`

### `get_document`

Reads one document as `ocost.document.v1`, like `GET /public/v1/documents/{document_id}`.

| Argument | Type | Meaning |
| --- | --- | --- |
| `document_id` | uuid, required | An id Ocost gave (a UUID) |

```json
{
  "name": "get_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

### `get_file`

Answers a file's status, reason and documents, like `GET /public/v1/files/{file_id}`.

| Argument | Type | Meaning |
| --- | --- | --- |
| `file_id` | uuid, required | An id Ocost gave (a UUID) |

```json
{
  "name": "get_file",
  "arguments": {
    "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1"
  }
}
```

### `list_files`

Lists files by their last change, oldest first, like `GET /public/v1/files`.

| Argument | Type | Meaning |
| --- | --- | --- |
| `status` | list of `received`, `reading`, `read`, `not_read`, `failed` | Only files in these statuses |
| `updated_since` | date-time | Files changed at or after this time (ISO 8601) |
| `cursor` | string | `next_cursor` of the page before |
| `limit` | integer 1–100, default `50` | Files per page. |

```json
{
  "name": "list_files",
  "arguments": {
    "status": ["read", "not_read", "failed"],
    "updated_since": "2026-11-09T08:00:00Z"
  }
}
```

### `read_document`

Reads a document's pages as text, up to 4 pages and 12,000 characters.

| Argument | Type | Meaning |
| --- | --- | --- |
| `document_id` | uuid, required | A document's id. |
| `pages` | list of integer | The file's page numbers to read. |

```json
{
  "name": "read_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
    "pages": [1, 2]
  }
}
```

### `find_documents`

Lists documents newest first, by kind, family or company.

| Argument | Type | Meaning |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (81 values) | One document type, as `kind_detail` in [Values](https://docs.ocost.io/en/document.md#values) lists them. |
| `company_id` | uuid | A company's id, from `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | A group of kinds, such as `invoices` or `contracts`. |

```json
{
  "name": "find_documents",
  "arguments": {
    "kind": "credit_note",
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_contracts`

Lists contracts with their term, notice and recurring amounts.

| Argument | Type | Meaning |
| --- | --- | --- |
| `company_id` | uuid | A company's id, from `find_company`. |

```json
{
  "name": "find_contracts",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_company`

Finds suppliers and customers by name, with their ids.

| Argument | Type | Meaning |
| --- | --- | --- |
| `name` | string, default `""` | Part of the name. Without it, all are listed. |

```json
{
  "name": "find_company",
  "arguments": {
    "name": "Musterbüro"
  }
}
```

### `find_project`

Finds projects by name, with their ids.

| Argument | Type | Meaning |
| --- | --- | --- |
| `name` | string, default `""` | Part of the name. Without it, all are listed. |

```json
{
  "name": "find_project",
  "arguments": {
    "name": "Neubau"
  }
}
```

### `company_documents`

Lists a company's documents in both directions, up to 30.

| Argument | Type | Meaning |
| --- | --- | --- |
| `company_id` | uuid, required | A company's id, from `find_company`. |

```json
{
  "name": "company_documents",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `invoice_detail`

Shows one invoice as its page in Ocost does: amounts, due date, discount, order and trail.

| Argument | Type | Meaning |
| --- | --- | --- |
| `invoice_id` | uuid, required | An invoice's id. |

```json
{
  "name": "invoice_detail",
  "arguments": {
    "invoice_id": "01a1b08c-8c3d-7f41-a2b5-3e4f5a6b7c8d"
  }
}
```

### `open_decisions`

Lists the connected person's open decisions, due first.

Only through an OAuth connection, as the person who allowed it.

| Argument | Type | Meaning |
| --- | --- | --- |
| `company_id` | uuid | A company's id, from `find_company`. |
| `project_id` | uuid | A project's id, from `find_project`. |

```json
{
  "name": "open_decisions",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `check_invoice`

Checks supplier invoices against § 14 UStG, and whether each is an e-invoice.

| Argument | Type | Meaning |
| --- | --- | --- |
| `document_ids` | list of uuid | The invoices to check, by their ids. |
| `company_id` | uuid | A company's id, from `find_company`. |
| `issued_since` | date | The issue date, from. |
| `issued_until` | date | The issue date, up to. |
| `only_missing` | boolean, default `false` | Only invoices that lack something. |
| `title` | string | The table's title. |

```json
{
  "name": "check_invoice",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c",
    "issued_since": "2026-01-01",
    "only_missing": true
  }
}
```

## `documents:write`

### `send_file`

Sends a file as base64, like `POST /public/v1/files`.

| Argument | Type | Meaning |
| --- | --- | --- |
| `filename` | string, required | Its name, e.g. bill.pdf |
| `content_base64` | string, required | The file's bytes in base64: a PDF, an image (JPEG, PNG, TIFF, WebP) or an e-invoice's XML (XRechnung, UBL, CII), at most 25 MB |
| `external_ref` | string | Your own id for it, e.g. an Odoo bill's 'account.move,42'; kept and given back |

```json
{
  "name": "send_file",
  "arguments": {
    "filename": "invoice.pdf",
    "content_base64": "JVBERi0xLjcK…",
    "external_ref": "account.move,42"
  }
}
```

## `search:read`

### `search_documents`

Searches what documents say, by exact text, keywords, meaning or both.

| Argument | Type | Meaning |
| --- | --- | --- |
| `query` | string, required | What to find. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, default `"hybrid"` | `exact` as written, `keywords` by words, `meaning` by meaning, `hybrid` both. |
| `document_id` | uuid | Search this document only. |
| `kinds` | list of `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (81 values) | Only these document types, as `kind_detail` in [Values](https://docs.ocost.io/en/document.md#values) lists them. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | A group of kinds, such as `invoices` or `contracts`. |
| `company_id` | uuid | A company's id, from `find_company`. |
| `project_id` | uuid | A project's id, from `find_project`. |
| `site_id` | uuid | A site's id. |
| `issued_since` | date | The issue date, from. |
| `issued_until` | date | The issue date, up to. |
| `due_since` | date | An invoice's due date, from. |
| `due_until` | date | An invoice's due date, up to. |
| `gross_min` | decimal | The gross from, in the business's currency. |
| `gross_max` | decimal | The gross up to, in the business's currency. |
| `direction` | `incoming`, `outgoing` | `incoming` from suppliers, `outgoing` to customers. |
| `status` | `open`, `paid` | An invoice's: `open` or `paid`. |
| `category` | string | An ECLASS code of any level, from `find_category`. |
| `limit` | integer | How many rows at most. |
| `title` | string | The table's title. |

```json
{
  "name": "search_documents",
  "arguments": {
    "query": "Bürostuhl",
    "match": "hybrid",
    "kinds": ["invoice"],
    "issued_since": "2026-01-01"
  }
}
```

### `search`

Searches documents for ChatGPT's deep research and company knowledge.

| Argument | Type | Meaning |
| --- | --- | --- |
| `query` | string, required | What to find |

```json
{
  "name": "search",
  "arguments": {
    "query": "Wartungsvertrag Aufzug"
  }
}
```

### `fetch`

Fetches a `search` result whole: its first four pages, up to 12,000 characters.

| Argument | Type | Meaning |
| --- | --- | --- |
| `id` | string, required | A result's id |

```json
{
  "name": "fetch",
  "arguments": {
    "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

## `figures:read`

### `find_category`

Turns words in any of Ocost's languages into ECLASS codes.

| Argument | Type | Meaning |
| --- | --- | --- |
| `words` | string, required | Words for a category, in any of Ocost's languages. |

```json
{
  "name": "find_category",
  "arguments": {
    "words": "Büromaterial"
  }
}
```

### `company_profile`

Sums up a company's last 12 months: bought, sold, terms, open items and payment times.

| Argument | Type | Meaning |
| --- | --- | --- |
| `company_id` | uuid, required | A company's id, from `find_company`. |

```json
{
  "name": "company_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `project_overview`

Compares a project's plan with what was spent and committed, by supplier and month.

| Argument | Type | Meaning |
| --- | --- | --- |
| `project_id` | uuid, required | A project's id, from `find_project`. |

```json
{
  "name": "project_overview",
  "arguments": {
    "project_id": "01a1b08c-4b1c-7d20-9a4b-2c3d4e5f6a7b"
  }
}
```

### `query_figures`

Adds up records for a chart, a comparison or a count.

| Argument | Type | Meaning |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (11 values), required | What to add up, such as `invoices` or `lines`. |
| `group_by` | list of object (`field`, `bucket`, `level`), required | One or two fields: the rows, then the columns. |
| `measure` | object (`agg`, `field`, `signed`) | What to add up: a count, or a field's sum, average, minimum or maximum. |
| `filters` | list of object (`field`, `values`, `since`, `until`, `min`, `max`) | Conditions on the source's fields. |
| `year` | integer | A year to add up. `period` replaces it. |
| `compare` | `previous_period`, `previous_year` | Compare with the period before, or the same period a year earlier. |
| `top_n` | integer | Only the largest groups. |
| `matching` | object (`query`, `match`) | Only the documents a search finds. |
| `title` | string | The table's title. |
| `period` | string | Plain words, such as `2025`, `Q3 2025` or `last year`. |

```json
{
  "name": "query_figures",
  "arguments": {
    "source": "invoices",
    "measure": {"agg": "sum", "field": "net"},
    "group_by": [{"field": "company"}],
    "filters": [{"field": "direction", "values": ["incoming"]}],
    "period": "2025",
    "top_n": 10
  }
}
```

### `top_companies`

Ranks the top suppliers or customers by net over a period.

| Argument | Type | Meaning |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, default `"suppliers"` | Suppliers (the default) or customers. |
| `period` | string | Plain words, such as `2025`, `Q3 2025` or `last year`. |
| `since` | date | From this date. |
| `until` | date | Up to this date. |
| `category` | string | An ECLASS code, or words. |
| `n` | integer, default `10` | How many to list. |
| `title` | string | The table's title. |

```json
{
  "name": "top_companies",
  "arguments": {
    "side": "suppliers",
    "period": "2025",
    "n": 10
  }
}
```

### `spend_over_time`

Gives net by month, quarter or year, by company or category if asked.

| Argument | Type | Meaning |
| --- | --- | --- |
| `period` | string | Plain words, such as `2025`, `Q3 2025` or `last year`. |
| `bucket` | `month`, `quarter`, `year`, default `"month"` | Month (the default), quarter or year. |
| `by` | `company`, `category` | A column per company, or per ECLASS segment. |
| `side` | `suppliers`, `customers`, default `"suppliers"` | Suppliers (the default) or customers. |
| `since` | date | From this date. |
| `until` | date | Up to this date. |
| `title` | string | The table's title. |

```json
{
  "name": "spend_over_time",
  "arguments": {
    "period": "last 12 months",
    "bucket": "month",
    "by": "company"
  }
}
```

### `largest_documents`

Lists the largest documents by gross over a period.

| Argument | Type | Meaning |
| --- | --- | --- |
| `kind` | string | A kind other than invoices to pay, such as `credit_note`. |
| `side` | `suppliers`, `customers`, default `"suppliers"` | Suppliers (the default) or customers. |
| `period` | string | Plain words, such as `2025`, `Q3 2025` or `last year`. |
| `since` | date | From this date. |
| `until` | date | Up to this date. |
| `n` | integer, default `10` | How many to list. |
| `title` | string | The table's title. |

```json
{
  "name": "largest_documents",
  "arguments": {
    "period": "Q3 2025",
    "n": 10
  }
}
```

### `payables_due`

Lists unpaid supplier invoices due in a window, Skonto deadlines first.

| Argument | Type | Meaning |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | When the invoices are due. |
| `since` | date | From this date. |
| `until` | date | Up to this date. |
| `company_id` | uuid | A company's id, from `find_company`. |
| `title` | string | The table's title. |

```json
{
  "name": "payables_due",
  "arguments": {
    "window": "next_14_days"
  }
}
```

### `vat_preview`

Previews a USt-Voranmeldung by Kennzahl, for the tax adviser to check.

| Argument | Type | Meaning |
| --- | --- | --- |
| `period` | string | A month (`2026-10`) or a quarter (`2026-Q4`). |
| `kz` | string | A Kennzahl, to list its invoices. |
| `title` | string | The table's title. |

```json
{
  "name": "vat_preview",
  "arguments": {
    "period": "2026-10"
  }
}
```

### `find_anomalies`

Flags duplicate invoices, changed bank accounts and prices above the order.

| Argument | Type | Meaning |
| --- | --- | --- |
| `since` | date | From this date. |
| `until` | date | Up to this date. |
| `kinds` | list of `duplicate`, `bank_changed`, `price_above_order` | Only these flags. |
| `title` | string | The table's title. |

```json
{
  "name": "find_anomalies",
  "arguments": {
    "since": "2026-08-01",
    "until": "2026-10-31",
    "kinds": ["bank_changed"]
  }
}
```

### `supplier_profile`

Sums up a supplier in one call: spend, terms, payment speed, open items and prices.

| Argument | Type | Meaning |
| --- | --- | --- |
| `company_id` | uuid, required | A company's id, from `find_company`. |

```json
{
  "name": "supplier_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

## `exports:write`

### `export_table`

Exports a table another tool returned as Excel or CSV, behind a link valid for 30 minutes.

| Argument | Type | Meaning |
| --- | --- | --- |
| `query` | object (`tool`, `args`), required | A table's `query`, unchanged, as a tool returned it. |
| `title` | string, default `"Ocost"` | The table's title. |
| `format` | `xlsx`, `csv`, default `"xlsx"` | Excel (`xlsx`, the default) or CSV. |

```json
{
  "name": "export_table",
  "arguments": {
    "query": {"tool": "top_companies", "args": {"period": "2025"}},
    "title": "Top suppliers 2025",
    "format": "xlsx"
  }
}
```

### `make_datev_export`

Makes the DATEV export of a period as one ZIP, behind a signed link.

Only through an OAuth connection, as the person who allowed it.

| Argument | Type | Meaning |
| --- | --- | --- |
| `starts_on` | date, required | The period's first day. |
| `ends_on` | date, required | The period's last day, in the same fiscal year. |

```json
{
  "name": "make_datev_export",
  "arguments": {
    "starts_on": "2026-10-01",
    "ends_on": "2026-10-31"
  }
}
```