Herramientas MCP
Cada herramienta del servidor MCP, escrita a partir de sus propias definiciones. Conectar un asistente configura el servidor. Un asistente lee la descripción completa de cada herramienta en tools/list. Las descripciones de los argumentos están ahí en inglés, como aquí.
documents:read
get_document
Lee un documento como ocost.document.v1, como GET /public/v1/documents/{document_id}.
| Argumento | Tipo | Significado |
|---|---|---|
document_id | uuid, obligatorio | An id Ocost gave (a UUID) |
{
"name": "get_document",
"arguments": {
"document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
}
}get_file
Responde el estado, el motivo y los documentos de un archivo, como GET /public/v1/files/{file_id}.
| Argumento | Tipo | Significado |
|---|---|---|
file_id | uuid, obligatorio | An id Ocost gave (a UUID) |
{
"name": "get_file",
"arguments": {
"file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1"
}
}list_files
Lista los archivos por su último cambio, el más antiguo primero, como GET /public/v1/files.
| Argumento | Tipo | Significado |
|---|---|---|
status | lista de 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, por defecto 50 | Archivos por página. |
{
"name": "list_files",
"arguments": {
"status": ["read", "not_read", "failed"],
"updated_since": "2026-11-09T08:00:00Z"
}
}read_document
Lee las páginas de un documento como texto, hasta 4 páginas y 12.000 caracteres.
| Argumento | Tipo | Significado |
|---|---|---|
document_id | uuid, obligatorio | El id de un documento. |
pages | lista de integer | Los números de página del archivo que leer. |
{
"name": "read_document",
"arguments": {
"document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
"pages": [1, 2]
}
}find_documents
Lista documentos, el más reciente primero, por tipo, familia o empresa.
| Argumento | Tipo | Significado |
|---|---|---|
kind | acceptance_protocol, agreement, bonus_payment_notification, … (82 valores) | Un tipo de documento, como los lista kind_detail en Valores. |
company_id | uuid | El id de una empresa, de find_company. |
family | invoices, payments, buying, contracts, reports, people, other | Un grupo de tipos, como invoices o contracts. |
{
"name": "find_documents",
"arguments": {
"kind": "credit_note",
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}find_contracts
Lista contratos con su duración, su preaviso y sus importes recurrentes.
| Argumento | Tipo | Significado |
|---|---|---|
company_id | uuid | El id de una empresa, de find_company. |
{
"name": "find_contracts",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}find_company
Encuentra proveedores y clientes por nombre, con sus ids.
| Argumento | Tipo | Significado |
|---|---|---|
name | string, por defecto "" | Parte del nombre. Sin él, se listan todos. |
country | string | Solo empresas cuya dirección principal está en este país (ISO 3166-1 alpha-2, DE). |
relation | supplier, customer | Solo proveedores o solo clientes. |
{
"name": "find_company",
"arguments": {
"name": "Musterbüro"
}
}find_project
Encuentra proyectos por nombre, con sus ids.
| Argumento | Tipo | Significado |
|---|---|---|
name | string, por defecto "" | Parte del nombre. Sin él, se listan todos. |
{
"name": "find_project",
"arguments": {
"name": "Neubau"
}
}company_documents
Lista los documentos de una empresa en ambas direcciones, hasta 30.
| Argumento | Tipo | Significado |
|---|---|---|
company_id | uuid, obligatorio | El id de una empresa, de find_company. |
{
"name": "company_documents",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}invoice_detail
Muestra una factura como lo hace su página en Ocost: importes, vencimiento, descuento, pedido e historial.
| Argumento | Tipo | Significado |
|---|---|---|
invoice_id | uuid, obligatorio | El id de una factura. |
{
"name": "invoice_detail",
"arguments": {
"invoice_id": "01a1b08c-8c3d-7f41-a2b5-3e4f5a6b7c8d"
}
}open_decisions
Lista las decisiones abiertas de la persona conectada, las que vencen primero.
Solo a través de una conexión OAuth, como la persona que la autorizó.
| Argumento | Tipo | Significado |
|---|---|---|
company_id | uuid | El id de una empresa, de find_company. |
project_id | uuid | El id de un proyecto, de find_project. |
{
"name": "open_decisions",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}check_invoice
Comprueba facturas de proveedor según el § 14 UStG, y si cada una es una factura electrónica.
| Argumento | Tipo | Significado |
|---|---|---|
document_ids | lista de uuid | Las facturas que comprobar, por sus ids. |
company_id | uuid | El id de una empresa, de find_company. |
issued_since | date | La fecha de emisión, desde. |
issued_until | date | La fecha de emisión, hasta. |
only_missing | boolean, por defecto false | Solo las facturas a las que les falta algo. |
title | string | El título de la tabla. |
{
"name": "check_invoice",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c",
"issued_since": "2026-01-01",
"only_missing": true
}
}documents:write
send_file
Envía un archivo en base64, como POST /public/v1/files.
| Argumento | Tipo | Significado |
|---|---|---|
filename | string, obligatorio | Its name, e.g. bill.pdf |
content_base64 | string, obligatorio | 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 |
{
"name": "send_file",
"arguments": {
"filename": "invoice.pdf",
"content_base64": "JVBERi0xLjcK…",
"external_ref": "account.move,42"
}
}search:read
search_documents
Busca lo que dicen los documentos, por texto exacto, palabras clave, significado o ambos.
| Argumento | Tipo | Significado |
|---|---|---|
query | string, obligatorio | Qué encontrar. |
match | exact, keywords, meaning, hybrid, por defecto "hybrid" | exact tal como está escrito, keywords por palabras, meaning por significado, hybrid ambos. |
document_id | uuid | Buscar solo en este documento. |
kinds | lista de acceptance_protocol, agreement, bonus_payment_notification, … (82 valores) | Solo estos tipos de documento, como los lista kind_detail en Valores. |
family | invoices, payments, buying, contracts, reports, people, other | Un grupo de tipos, como invoices o contracts. |
company_id | uuid | El id de una empresa, de find_company. |
project_id | uuid | El id de un proyecto, de find_project. |
site_id | uuid | El id de una sede. |
issued_since | date | La fecha de emisión, desde. |
issued_until | date | La fecha de emisión, hasta. |
due_since | date | La fecha de vencimiento de una factura, desde. |
due_until | date | La fecha de vencimiento de una factura, hasta. |
gross_min | decimal | El bruto desde, en la moneda de la empresa. |
gross_max | decimal | El bruto hasta, en la moneda de la empresa. |
direction | incoming, outgoing | incoming de proveedores, outgoing a clientes. |
status | open, paid | El de una factura: open o paid. |
category | string | Un código ECLASS de cualquier nivel, de find_category. |
limit | integer | Cuántas filas como máximo. |
title | string | El título de la tabla. |
{
"name": "search_documents",
"arguments": {
"query": "Bürostuhl",
"match": "hybrid",
"kinds": ["invoice"],
"issued_since": "2026-01-01"
}
}search
Busca documentos para la investigación profunda y el conocimiento de empresa de ChatGPT.
| Argumento | Tipo | Significado |
|---|---|---|
query | string, obligatorio | What to find |
{
"name": "search",
"arguments": {
"query": "Wartungsvertrag Aufzug"
}
}fetch
Obtiene un resultado de search completo: sus cuatro primeras páginas, hasta 12.000 caracteres.
| Argumento | Tipo | Significado |
|---|---|---|
id | string, obligatorio | A result's id |
{
"name": "fetch",
"arguments": {
"id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
}
}figures:read
find_category
Convierte palabras en cualquiera de los idiomas de Ocost en códigos ECLASS.
| Argumento | Tipo | Significado |
|---|---|---|
words | string, obligatorio | Palabras para una categoría, en cualquiera de los idiomas de Ocost. |
{
"name": "find_category",
"arguments": {
"words": "Büromaterial"
}
}company_profile
Resume los últimos 12 meses de una empresa: comprado, vendido, condiciones, partidas abiertas y plazos de pago.
| Argumento | Tipo | Significado |
|---|---|---|
company_id | uuid, obligatorio | El id de una empresa, de find_company. |
{
"name": "company_profile",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}project_overview
Compara el plan de un proyecto con lo gastado y lo comprometido, por proveedor y por mes.
| Argumento | Tipo | Significado |
|---|---|---|
project_id | uuid, obligatorio | El id de un proyecto, de find_project. |
{
"name": "project_overview",
"arguments": {
"project_id": "01a1b08c-4b1c-7d20-9a4b-2c3d4e5f6a7b"
}
}query_figures
Suma registros para un gráfico, una comparación o un recuento.
| Argumento | Tipo | Significado |
|---|---|---|
source | documents, lines, invoices, … (11 valores), obligatorio | Qué sumar, como invoices o lines. |
group_by | lista de objeto (field, bucket, level), obligatorio | Uno o dos campos: las filas, después las columnas. |
measure | objeto (agg, field, signed) | Qué sumar: un recuento, o la suma, la media, el mínimo o el máximo de un campo. |
filters | lista de objeto (field, values, since, until, min, max) | Condiciones sobre los campos de la fuente. |
year | integer | Un año que sumar. period lo sustituye. |
compare | previous_period, previous_year | Comparar con el periodo anterior, o con el mismo periodo un año antes. |
top_n | integer | Solo los grupos más grandes. |
matching | objeto (query, match) | Solo los documentos que encuentra una búsqueda. |
title | string | El título de la tabla. |
period | string | Palabras sencillas, como 2025, Q3 2025 o last year. |
{
"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
Clasifica los principales proveedores o clientes por neto en un periodo.
| Argumento | Tipo | Significado |
|---|---|---|
side | suppliers, customers, por defecto "suppliers" | Proveedores (por defecto) o clientes. |
period | string | Palabras sencillas, como 2025, Q3 2025 o last year. |
since | date | Desde esta fecha. |
until | date | Hasta esta fecha. |
category | string | Un código ECLASS, o palabras. |
n | integer, por defecto 10 | Cuántos listar. |
title | string | El título de la tabla. |
{
"name": "top_companies",
"arguments": {
"side": "suppliers",
"period": "2025",
"n": 10
}
}spend_over_time
Da el neto por mes, trimestre o año, por empresa o categoría si se pide.
| Argumento | Tipo | Significado |
|---|---|---|
period | string | Palabras sencillas, como 2025, Q3 2025 o last year. |
bucket | month, quarter, year, por defecto "month" | Mes (por defecto), trimestre o año. |
by | company, category | Una columna por empresa, o por segmento ECLASS. |
side | suppliers, customers, por defecto "suppliers" | Proveedores (por defecto) o clientes. |
since | date | Desde esta fecha. |
until | date | Hasta esta fecha. |
title | string | El título de la tabla. |
{
"name": "spend_over_time",
"arguments": {
"period": "last 12 months",
"bucket": "month",
"by": "company"
}
}largest_documents
Lista los documentos más grandes por bruto en un periodo.
| Argumento | Tipo | Significado |
|---|---|---|
kind | string | Un tipo distinto de las facturas por pagar, como credit_note. |
side | suppliers, customers, por defecto "suppliers" | Proveedores (por defecto) o clientes. |
period | string | Palabras sencillas, como 2025, Q3 2025 o last year. |
since | date | Desde esta fecha. |
until | date | Hasta esta fecha. |
n | integer, por defecto 10 | Cuántos listar. |
title | string | El título de la tabla. |
{
"name": "largest_documents",
"arguments": {
"period": "Q3 2025",
"n": 10
}
}payables_due
Lista las facturas de proveedor sin pagar que vencen en un intervalo, primero los plazos de Skonto.
| Argumento | Tipo | Significado |
|---|---|---|
window | this_week, next_7_days, next_14_days, next_30_days, this_month | Cuándo vencen las facturas. |
since | date | Desde esta fecha. |
until | date | Hasta esta fecha. |
company_id | uuid | El id de una empresa, de find_company. |
title | string | El título de la tabla. |
{
"name": "payables_due",
"arguments": {
"window": "next_14_days"
}
}vat_preview
Anticipa una USt-Voranmeldung por Kennzahl, para que la revise el asesor fiscal.
| Argumento | Tipo | Significado |
|---|---|---|
period | string | Un mes (2026-10) o un trimestre (2026-Q4). |
kz | string | Una Kennzahl, para listar sus facturas. |
title | string | El título de la tabla. |
{
"name": "vat_preview",
"arguments": {
"period": "2026-10"
}
}find_anomalies
Señala facturas duplicadas, cuentas bancarias cambiadas y precios por encima del pedido.
| Argumento | Tipo | Significado |
|---|---|---|
since | date | Desde esta fecha. |
until | date | Hasta esta fecha. |
kinds | lista de duplicate, bank_changed, price_above_order | Solo estas señales. |
title | string | El título de la tabla. |
{
"name": "find_anomalies",
"arguments": {
"since": "2026-08-01",
"until": "2026-10-31",
"kinds": ["bank_changed"]
}
}supplier_profile
Resume un proveedor en una llamada: gasto, condiciones, rapidez de pago, partidas abiertas y precios.
| Argumento | Tipo | Significado |
|---|---|---|
company_id | uuid, obligatorio | El id de una empresa, de find_company. |
{
"name": "supplier_profile",
"arguments": {
"company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
}
}exports:write
export_table
Exporta como Excel o CSV una tabla que devolvió otra herramienta, tras un enlace válido 30 minutos.
| Argumento | Tipo | Significado |
|---|---|---|
query | objeto (tool, args), obligatorio | La query de una tabla, sin cambios, tal como la devolvió una herramienta. |
title | string, por defecto "Ocost" | El título de la tabla. |
format | xlsx, csv, por defecto "xlsx" | Excel (xlsx, por defecto) o CSV. |
{
"name": "export_table",
"arguments": {
"query": {"tool": "top_companies", "args": {"period": "2025"}},
"title": "Top suppliers 2025",
"format": "xlsx"
}
}make_datev_export
Crea la exportación DATEV de un periodo como un ZIP, tras un enlace firmado.
Solo a través de una conexión OAuth, como la persona que la autorizó.
| Argumento | Tipo | Significado |
|---|---|---|
starts_on | date, obligatorio | El primer día del periodo. |
ends_on | date, obligatorio | El último día del periodo, en el mismo ejercicio fiscal. |
{
"name": "make_datev_export",
"arguments": {
"starts_on": "2026-10-01",
"ends_on": "2026-10-31"
}
}