# Herramientas MCP
> Cada herramienta del servidor MCP, por permiso: qué hace, sus argumentos y una llamada de ejemplo.
>
> Antes: [Conectar un asistente](https://ocost.io/docs/es/mcp.md)

Cada herramienta del servidor MCP, escrita a partir de sus propias definiciones. [Conectar un asistente](https://ocost.io/docs/es/mcp.md) 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) |

```json
{
  "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) |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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](https://ocost.io/docs/es/document.md#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`. |

```json
{
  "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`. |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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`. |

```json
{
  "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. |

```json
{
  "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`. |

```json
{
  "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. |

```json
{
  "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 |

```json
{
  "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](https://ocost.io/docs/es/document.md#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. |

```json
{
  "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 |

```json
{
  "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 |

```json
{
  "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. |

```json
{
  "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`. |

```json
{
  "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`. |

```json
{
  "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`. |

```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`

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. |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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. |

```json
{
  "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`. |

```json
{
  "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. |

```json
{
  "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. |

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

## Véase también

- [Conectar un asistente](https://ocost.io/docs/es/mcp.md): Conectar un asistente al servidor MCP (https://api.ocost.io/public/mcp, las mismas claves): Claude Code, Claude Desktop, Cursor, claude.ai y ChatGPT por OAuth, y cualquier cliente.
- [Claves y permisos](https://ocost.io/docs/es/authentication.md): Claves de API: cómo las lleva una solicitud, cómo rotarlas, sus permisos y los rechazos.
- [El documento](https://ocost.io/docs/es/document.md): El esquema ocost.document.v1 en términos de EN 16931 (se corresponde con UBL y CII): un ejemplo, tipo y dirección, fuentes, comprobaciones, versiones, y cada campo y valor.
- En ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
