# Інструменти MCP
> Кожен інструмент сервера MCP за дозволом: що він робить, його аргументи і приклад виклику.
>
> Спершу: [Підключити асистента](https://ocost.io/docs/uk/mcp.md)

Кожен інструмент сервера MCP, записаний з його власних визначень. [Підключити асистента](https://ocost.io/docs/uk/mcp.md) налаштовує сервер. Асистент читає повний опис кожного інструмента в `tools/list`. Описи аргументів там, як і тут, англійською.

## `documents:read`

### `get_document`

Читає один документ як `ocost.document.v1`, як `GET /public/v1/documents/{document_id}`.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `document_id` | uuid, обов'язково | An id Ocost gave (a UUID) |

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

### `get_file`

Повертає статус файлу, причину і документи, як `GET /public/v1/files/{file_id}`.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `file_id` | uuid, обов'язково | An id Ocost gave (a UUID) |

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

### `list_files`

Перелічує файли за останньою зміною, від найстаріших, як `GET /public/v1/files`.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `status` | список `received`, `reading`, `read`, `not_read`, `failed`, `needs_company` | Only files in these statuses |
| `updated_since` | date-time | Files changed at or after this time (ISO 8601) |
| `external_ref` | string | Only the files carrying this id of yours among their external_refs |
| `cursor` | string | `next_cursor` of the page before |
| `limit` | integer 1–100, типово `50` | Файлів на сторінку. |

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

### `read_document`

Читає сторінки документа як текст, до 4 сторінок і 12 000 символів.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `document_id` | uuid, обов'язково | Ідентифікатор документа. |
| `pages` | список integer | Номери сторінок файлу, які треба прочитати. |

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

### `find_documents`

Перелічує документи від найновіших, за видом, групою або компанією.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 значень) | Один тип документа, як `kind_detail` їх перелічує в [Значення](https://ocost.io/docs/uk/document.md#значення). |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Група видів, наприклад `invoices` або `contracts`. |

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

### `find_contracts`

Перелічує договори з їхнім строком, повідомленням про розірвання і регулярними сумами.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |

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

### `find_company`

Знаходить постачальників і клієнтів за назвою, з їхніми ідентифікаторами.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `name` | string, типово `""` | Частина назви. Без неї перелічуються всі. |
| `country` | string | Лише компанії, чия основна адреса в цій країні (ISO 3166-1 alpha-2, `DE`). |
| `relation` | `supplier`, `customer` | Лише постачальники або лише клієнти. |

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

### `find_project`

Знаходить проєкти за назвою, з їхніми ідентифікаторами.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `name` | string, типово `""` | Частина назви. Без неї перелічуються всі. |

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

### `company_documents`

Перелічує документи компанії в обох напрямах, до 30.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `company_id` | uuid, обов'язково | Ідентифікатор компанії, з `find_company`. |

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

### `invoice_detail`

Показує один рахунок так, як його сторінка в Ocost: суми, строк оплати, знижку, замовлення та історію.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `invoice_id` | uuid, обов'язково | Ідентифікатор рахунку. |

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

### `open_decisions`

Перелічує відкриті рішення підключеної людини, спершу ті, що мають найближчий строк.

Лише через з'єднання OAuth, від імені людини, яка його дозволила.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |
| `project_id` | uuid | Ідентифікатор проєкту, з `find_project`. |

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

### `check_invoice`

Перевіряє рахунки постачальників за § 14 UStG і чи є кожен електронним рахунком.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `document_ids` | список uuid | Рахунки для перевірки, за їхніми ідентифікаторами. |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |
| `issued_since` | date | Дата документа, від. |
| `issued_until` | date | Дата документа, до. |
| `only_missing` | boolean, типово `false` | Лише рахунки, у яких чогось бракує. |
| `title` | string | Назва таблиці. |

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

## `documents:write`

### `send_file`

Надсилає файл як base64, як `POST /public/v1/files`.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `filename` | string, обов'язково | Its name, e.g. bill.pdf |
| `content_base64` | string, обов'язково | The file's bytes in base64: a PDF, an image (JPEG, PNG, TIFF, WebP), a Word file (.docx, .doc) 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, beside the ones sent with the same bytes before |

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

## `search:read`

### `search_documents`

Шукає в тексті документів: за точним текстом, ключовими словами, змістом або за обома.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `query` | string, обов'язково | Що знайти. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, типово `"hybrid"` | `exact` як написано, `keywords` за словами, `meaning` за змістом, `hybrid` за обома. |
| `document_id` | uuid | Шукати лише в цьому документі. |
| `kinds` | список `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 значень) | Лише ці типи документів, як `kind_detail` їх перелічує в [Значення](https://ocost.io/docs/uk/document.md#значення). |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Група видів, наприклад `invoices` або `contracts`. |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |
| `project_id` | uuid | Ідентифікатор проєкту, з `find_project`. |
| `site_id` | uuid | Ідентифікатор майданчика. |
| `issued_since` | date | Дата документа, від. |
| `issued_until` | date | Дата документа, до. |
| `due_since` | date | Строк оплати рахунку, від. |
| `due_until` | date | Строк оплати рахунку, до. |
| `gross_min` | десяткове число | Сума брутто від, у валюті компанії. |
| `gross_max` | десяткове число | Сума брутто до, у валюті компанії. |
| `direction` | `incoming`, `outgoing` | `incoming` від постачальників, `outgoing` клієнтам. |
| `status` | `open`, `paid` | Статус рахунку: `open` або `paid`. |
| `category` | string | Код ECLASS будь-якого рівня, з `find_category`. |
| `limit` | integer | Щонайбільше скільки рядків. |
| `title` | string | Назва таблиці. |

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

### `search`

Шукає документи для глибокого дослідження і знань компанії в ChatGPT.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `query` | string, обов'язково | What to find |

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

### `fetch`

Отримує результат `search` повністю: його перші чотири сторінки, до 12 000 символів.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `id` | string, обов'язково | A result's id |

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

## `figures:read`

### `find_category`

Перетворює слова будь-якою з мов Ocost на коди ECLASS.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `words` | string, обов'язково | Слова для категорії будь-якою з мов Ocost. |

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

### `company_profile`

Підсумовує останні 12 місяців компанії: куплене, продане, умови, відкриті позиції і строки оплати.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `company_id` | uuid, обов'язково | Ідентифікатор компанії, з `find_company`. |

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

### `project_overview`

Порівнює план проєкту з витраченим і зарезервованим, за постачальниками і місяцями.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `project_id` | uuid, обов'язково | Ідентифікатор проєкту, з `find_project`. |

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

### `query_figures`

Підсумовує записи для діаграми, порівняння або підрахунку.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (11 значень), обов'язково | Що підсумовувати, наприклад `invoices` або `lines`. |
| `group_by` | список об'єкт (`field`, `bucket`, `level`), обов'язково | Одне або два поля: рядки, потім стовпці. |
| `measure` | об'єкт (`agg`, `field`, `signed`) | Що підсумовувати: кількість або суму, середнє, мінімум чи максимум поля. |
| `filters` | список об'єкт (`field`, `values`, `since`, `until`, `min`, `max`) | Умови для полів джерела. |
| `year` | integer | Рік для підсумку. `period` його замінює. |
| `compare` | `previous_period`, `previous_year` | Порівняти з попереднім періодом або з тим самим періодом роком раніше. |
| `top_n` | integer | Лише найбільші групи. |
| `matching` | об'єкт (`query`, `match`) | Лише документи, які знаходить пошук. |
| `title` | string | Назва таблиці. |
| `period` | string | Звичайними словами, наприклад `2025`, `Q3 2025` або `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`

Ранжує найбільших постачальників або клієнтів за сумою нетто за період.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, типово `"suppliers"` | Постачальники (типово) або клієнти. |
| `period` | string | Звичайними словами, наприклад `2025`, `Q3 2025` або `last year`. |
| `since` | date | Від цієї дати. |
| `until` | date | До цієї дати. |
| `category` | string | Код ECLASS або слова. |
| `n` | integer, типово `10` | Скільки перелічити. |
| `title` | string | Назва таблиці. |

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

### `spend_over_time`

Дає суму нетто за місяцями, кварталами або роками, на запит — за компаніями чи категоріями.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `period` | string | Звичайними словами, наприклад `2025`, `Q3 2025` або `last year`. |
| `bucket` | `month`, `quarter`, `year`, типово `"month"` | Місяць (типово), квартал або рік. |
| `by` | `company`, `category` | Стовпець на кожну компанію або на кожен сегмент ECLASS. |
| `side` | `suppliers`, `customers`, типово `"suppliers"` | Постачальники (типово) або клієнти. |
| `since` | date | Від цієї дати. |
| `until` | date | До цієї дати. |
| `title` | string | Назва таблиці. |

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

### `largest_documents`

Перелічує найбільші документи за сумою брутто за період.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `kind` | string | Вид, відмінний від рахунків до оплати, наприклад `credit_note`. |
| `side` | `suppliers`, `customers`, типово `"suppliers"` | Постачальники (типово) або клієнти. |
| `period` | string | Звичайними словами, наприклад `2025`, `Q3 2025` або `last year`. |
| `since` | date | Від цієї дати. |
| `until` | date | До цієї дати. |
| `n` | integer, типово `10` | Скільки перелічити. |
| `title` | string | Назва таблиці. |

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

### `payables_due`

Перелічує неоплачені рахунки постачальників зі строком оплати у вікні, спершу строки Skonto.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | Коли настає строк оплати рахунків. |
| `since` | date | Від цієї дати. |
| `until` | date | До цієї дати. |
| `company_id` | uuid | Ідентифікатор компанії, з `find_company`. |
| `title` | string | Назва таблиці. |

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

### `vat_preview`

Попередньо показує USt-Voranmeldung за Kennzahl, щоб податковий консультант перевірив.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `period` | string | Місяць (`2026-10`) або квартал (`2026-Q4`). |
| `kz` | string | Kennzahl, щоб перелічити її рахунки. |
| `title` | string | Назва таблиці. |

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

### `find_anomalies`

Позначає дублікати рахунків, змінені банківські рахунки і ціни, вищі за замовлення.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `since` | date | Від цієї дати. |
| `until` | date | До цієї дати. |
| `kinds` | список `duplicate`, `bank_changed`, `price_above_order` | Лише ці позначки. |
| `title` | string | Назва таблиці. |

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

### `supplier_profile`

Підсумовує постачальника за один виклик: витрати, умови, швидкість оплати, відкриті позиції і ціни.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `company_id` | uuid, обов'язково | Ідентифікатор компанії, з `find_company`. |

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

## `exports:write`

### `export_table`

Експортує таблицю, яку повернув інший інструмент, в Excel або CSV за посиланням, дійсним 30 хвилин.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `query` | об'єкт (`tool`, `args`), обов'язково | `query` таблиці без змін, як його повернув інструмент. |
| `title` | string, типово `"Ocost"` | Назва таблиці. |
| `format` | `xlsx`, `csv`, типово `"xlsx"` | Excel (`xlsx`, типово) або CSV. |

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

### `make_datev_export`

Створює експорт DATEV за період одним ZIP за підписаним посиланням.

Лише через з'єднання OAuth, від імені людини, яка його дозволила.

| Аргумент | Тип | Зміст |
| --- | --- | --- |
| `starts_on` | date, обов'язково | Перший день періоду. |
| `ends_on` | date, обов'язково | Останній день періоду, у тому самому фінансовому році. |

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

## Див. також

- [Підключити асистента](https://ocost.io/docs/uk/mcp.md): Підключити асистента до сервера MCP (https://api.ocost.io/public/mcp, ті самі ключі): Claude Code, Claude Desktop, Cursor, claude.ai і ChatGPT через OAuth, а також будь-який клієнт.
- [Ключі та дозволи](https://ocost.io/docs/uk/authentication.md): Ключі API: як запит їх передає, заміна ключів, їхні дозволи і відмови.
- [Документ](https://ocost.io/docs/uk/document.md): Схема ocost.document.v1 у термінах EN 16931 (відображається на UBL і CII): приклад, вид і напрям, джерела, перевірки, версії, кожне поле і значення.
- На ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
