MCP tools

View as Markdown

Every tool of the MCP server, written from its own definitions. Connect an assistant 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 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 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"
  }
}