# Outils MCP
> Chaque outil du serveur MCP, par autorisation : ce qu'il fait, ses arguments et un exemple d'appel.
>
> Avant: [Connecter un assistant](https://ocost.io/docs/fr/mcp.md)

Chaque outil du serveur MCP, écrit à partir de ses propres définitions. [Connecter un assistant](https://ocost.io/docs/fr/mcp.md) configure le serveur. Un assistant lit la description complète de chaque outil dans `tools/list`. Les descriptions des arguments y sont en anglais, comme ici.

## `documents:read`

### `get_document`

Lit un document en `ocost.document.v1`, comme `GET /public/v1/documents/{document_id}`.

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

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

### `get_file`

Renvoie le statut, la raison et les documents d'un fichier, comme `GET /public/v1/files/{file_id}`.

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

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

### `list_files`

Liste les fichiers par leur dernière modification, du plus ancien au plus récent, comme `GET /public/v1/files`.

| Argument | Type | Signification |
| --- | --- | --- |
| `status` | liste 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, par défaut `50` | Fichiers par page. |

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

### `read_document`

Lit les pages d'un document en texte, jusqu'à 4 pages et 12 000 caractères.

| Argument | Type | Signification |
| --- | --- | --- |
| `document_id` | uuid, obligatoire | L'identifiant d'un document. |
| `pages` | liste de integer | Les numéros des pages du fichier à lire. |

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

### `find_documents`

Liste les documents du plus récent au plus ancien, par type, famille ou entreprise.

| Argument | Type | Signification |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 valeurs) | Un type de document, comme `kind_detail` les liste dans [Valeurs](https://ocost.io/docs/fr/document.md#valeurs). |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Un groupe de types, comme `invoices` ou `contracts`. |

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

### `find_contracts`

Liste les contrats avec leur durée, leur préavis et leurs montants récurrents.

| Argument | Type | Signification |
| --- | --- | --- |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |

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

### `find_company`

Trouve des fournisseurs et des clients par leur nom, avec leurs identifiants.

| Argument | Type | Signification |
| --- | --- | --- |
| `name` | string, par défaut `""` | Une partie du nom. Sans lui, tous sont listés. |
| `country` | string | Seulement les entreprises dont l'adresse principale est dans ce pays (ISO 3166-1 alpha-2, `DE`). |
| `relation` | `supplier`, `customer` | Seulement les fournisseurs ou seulement les clients. |

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

### `find_project`

Trouve des projets par leur nom, avec leurs identifiants.

| Argument | Type | Signification |
| --- | --- | --- |
| `name` | string, par défaut `""` | Une partie du nom. Sans lui, tous sont listés. |

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

### `company_documents`

Liste les documents d'une entreprise dans les deux sens, jusqu'à 30.

| Argument | Type | Signification |
| --- | --- | --- |
| `company_id` | uuid, obligatoire | L'identifiant d'une entreprise, issu de `find_company`. |

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

### `invoice_detail`

Montre une facture comme sa page dans Ocost : montants, échéance, escompte, commande et historique.

| Argument | Type | Signification |
| --- | --- | --- |
| `invoice_id` | uuid, obligatoire | L'identifiant d'une facture. |

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

### `open_decisions`

Liste les décisions ouvertes de la personne connectée, les plus urgentes d'abord.

Uniquement via une connexion OAuth, en tant que la personne qui l'a autorisée.

| Argument | Type | Signification |
| --- | --- | --- |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |
| `project_id` | uuid | L'identifiant d'un projet, issu de `find_project`. |

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

### `check_invoice`

Contrôle des factures fournisseurs selon le § 14 UStG, et si chacune est une facture électronique.

| Argument | Type | Signification |
| --- | --- | --- |
| `document_ids` | liste de uuid | Les factures à contrôler, par leurs identifiants. |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |
| `issued_since` | date | La date d'émission, à partir de. |
| `issued_until` | date | La date d'émission, jusqu'à. |
| `only_missing` | boolean, par défaut `false` | Seulement les factures auxquelles il manque quelque chose. |
| `title` | string | Le titre du tableau. |

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

## `documents:write`

### `send_file`

Envoie un fichier en base64, comme `POST /public/v1/files`.

| Argument | Type | Signification |
| --- | --- | --- |
| `filename` | string, obligatoire | Its name, e.g. bill.pdf |
| `content_base64` | string, obligatoire | 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`

Recherche ce que disent les documents, par texte exact, mots-clés, sens ou les deux.

| Argument | Type | Signification |
| --- | --- | --- |
| `query` | string, obligatoire | Ce qu'il faut trouver. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, par défaut `"hybrid"` | `exact` tel qu'écrit, `keywords` par mots, `meaning` par sens, `hybrid` les deux. |
| `document_id` | uuid | Rechercher uniquement dans ce document. |
| `kinds` | liste de `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 valeurs) | Seulement ces types de documents, comme `kind_detail` les liste dans [Valeurs](https://ocost.io/docs/fr/document.md#valeurs). |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Un groupe de types, comme `invoices` ou `contracts`. |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |
| `project_id` | uuid | L'identifiant d'un projet, issu de `find_project`. |
| `site_id` | uuid | L'identifiant d'un site. |
| `issued_since` | date | La date d'émission, à partir de. |
| `issued_until` | date | La date d'émission, jusqu'à. |
| `due_since` | date | La date d'échéance d'une facture, à partir de. |
| `due_until` | date | La date d'échéance d'une facture, jusqu'à. |
| `gross_min` | décimal | Le montant TTC à partir de, dans la devise de l'entreprise. |
| `gross_max` | décimal | Le montant TTC jusqu'à, dans la devise de l'entreprise. |
| `direction` | `incoming`, `outgoing` | `incoming` venant des fournisseurs, `outgoing` vers les clients. |
| `status` | `open`, `paid` | Celui d'une facture : `open` ou `paid`. |
| `category` | string | Un code ECLASS de n'importe quel niveau, issu de `find_category`. |
| `limit` | integer | Combien de lignes au plus. |
| `title` | string | Le titre du tableau. |

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

### `search`

Recherche des documents pour la recherche approfondie et le savoir d'entreprise de ChatGPT.

| Argument | Type | Signification |
| --- | --- | --- |
| `query` | string, obligatoire | What to find |

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

### `fetch`

Récupère un résultat de `search` en entier : ses quatre premières pages, jusqu'à 12 000 caractères.

| Argument | Type | Signification |
| --- | --- | --- |
| `id` | string, obligatoire | A result's id |

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

## `figures:read`

### `find_category`

Transforme des mots dans l'une des langues d'Ocost en codes ECLASS.

| Argument | Type | Signification |
| --- | --- | --- |
| `words` | string, obligatoire | Des mots pour une catégorie, dans l'une des langues d'Ocost. |

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

### `company_profile`

Résume les 12 derniers mois d'une entreprise : achats, ventes, conditions, postes ouverts et délais de paiement.

| Argument | Type | Signification |
| --- | --- | --- |
| `company_id` | uuid, obligatoire | L'identifiant d'une entreprise, issu de `find_company`. |

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

### `project_overview`

Compare le budget d'un projet avec ce qui a été dépensé et engagé, par fournisseur et par mois.

| Argument | Type | Signification |
| --- | --- | --- |
| `project_id` | uuid, obligatoire | L'identifiant d'un projet, issu de `find_project`. |

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

### `query_figures`

Additionne des enregistrements pour un graphique, une comparaison ou un décompte.

| Argument | Type | Signification |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (11 valeurs), obligatoire | Ce qu'il faut additionner, comme `invoices` ou `lines`. |
| `group_by` | liste de objet (`field`, `bucket`, `level`), obligatoire | Un ou deux champs : les lignes, puis les colonnes. |
| `measure` | objet (`agg`, `field`, `signed`) | Ce qu'il faut additionner : un décompte, ou la somme, la moyenne, le minimum ou le maximum d'un champ. |
| `filters` | liste de objet (`field`, `values`, `since`, `until`, `min`, `max`) | Des conditions sur les champs de la source. |
| `year` | integer | Une année à additionner. `period` la remplace. |
| `compare` | `previous_period`, `previous_year` | Comparer avec la période précédente, ou avec la même période un an plus tôt. |
| `top_n` | integer | Seulement les plus grands groupes. |
| `matching` | objet (`query`, `match`) | Seulement les documents qu'une recherche trouve. |
| `title` | string | Le titre du tableau. |
| `period` | string | En mots simples, comme `2025`, `Q3 2025` ou `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`

Classe les principaux fournisseurs ou clients par montant HT sur une période.

| Argument | Type | Signification |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, par défaut `"suppliers"` | Les fournisseurs (par défaut) ou les clients. |
| `period` | string | En mots simples, comme `2025`, `Q3 2025` ou `last year`. |
| `since` | date | À partir de cette date. |
| `until` | date | Jusqu'à cette date. |
| `category` | string | Un code ECLASS, ou des mots. |
| `n` | integer, par défaut `10` | Combien en lister. |
| `title` | string | Le titre du tableau. |

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

### `spend_over_time`

Donne le montant HT par mois, trimestre ou année, par entreprise ou catégorie si demandé.

| Argument | Type | Signification |
| --- | --- | --- |
| `period` | string | En mots simples, comme `2025`, `Q3 2025` ou `last year`. |
| `bucket` | `month`, `quarter`, `year`, par défaut `"month"` | Mois (par défaut), trimestre ou année. |
| `by` | `company`, `category` | Une colonne par entreprise, ou par segment ECLASS. |
| `side` | `suppliers`, `customers`, par défaut `"suppliers"` | Les fournisseurs (par défaut) ou les clients. |
| `since` | date | À partir de cette date. |
| `until` | date | Jusqu'à cette date. |
| `title` | string | Le titre du tableau. |

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

### `largest_documents`

Liste les plus gros documents par montant TTC sur une période.

| Argument | Type | Signification |
| --- | --- | --- |
| `kind` | string | Un type autre que les factures à payer, comme `credit_note`. |
| `side` | `suppliers`, `customers`, par défaut `"suppliers"` | Les fournisseurs (par défaut) ou les clients. |
| `period` | string | En mots simples, comme `2025`, `Q3 2025` ou `last year`. |
| `since` | date | À partir de cette date. |
| `until` | date | Jusqu'à cette date. |
| `n` | integer, par défaut `10` | Combien en lister. |
| `title` | string | Le titre du tableau. |

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

### `payables_due`

Liste les factures fournisseurs impayées échues dans une fenêtre, les échéances d'escompte d'abord.

| Argument | Type | Signification |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | Quand les factures sont échues. |
| `since` | date | À partir de cette date. |
| `until` | date | Jusqu'à cette date. |
| `company_id` | uuid | L'identifiant d'une entreprise, issu de `find_company`. |
| `title` | string | Le titre du tableau. |

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

### `vat_preview`

Prévisualise une USt-Voranmeldung par Kennzahl, que le conseiller fiscal vérifie.

| Argument | Type | Signification |
| --- | --- | --- |
| `period` | string | Un mois (`2026-10`) ou un trimestre (`2026-Q4`). |
| `kz` | string | Une Kennzahl, pour lister ses factures. |
| `title` | string | Le titre du tableau. |

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

### `find_anomalies`

Signale les factures en double, les comptes bancaires modifiés et les prix supérieurs à la commande.

| Argument | Type | Signification |
| --- | --- | --- |
| `since` | date | À partir de cette date. |
| `until` | date | Jusqu'à cette date. |
| `kinds` | liste de `duplicate`, `bank_changed`, `price_above_order` | Seulement ces signalements. |
| `title` | string | Le titre du tableau. |

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

### `supplier_profile`

Résume un fournisseur en un appel : dépenses, conditions, rapidité de paiement, postes ouverts et prix.

| Argument | Type | Signification |
| --- | --- | --- |
| `company_id` | uuid, obligatoire | L'identifiant d'une entreprise, issu de `find_company`. |

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

## `exports:write`

### `export_table`

Exporte un tableau renvoyé par un autre outil en Excel ou CSV, derrière un lien valable 30 minutes.

| Argument | Type | Signification |
| --- | --- | --- |
| `query` | objet (`tool`, `args`), obligatoire | La `query` d'un tableau, inchangée, telle qu'un outil l'a renvoyée. |
| `title` | string, par défaut `"Ocost"` | Le titre du tableau. |
| `format` | `xlsx`, `csv`, par défaut `"xlsx"` | Excel (`xlsx`, par défaut) ou CSV. |

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

### `make_datev_export`

Crée l'export DATEV d'une période en un seul ZIP, derrière un lien signé.

Uniquement via une connexion OAuth, en tant que la personne qui l'a autorisée.

| Argument | Type | Signification |
| --- | --- | --- |
| `starts_on` | date, obligatoire | Le premier jour de la période. |
| `ends_on` | date, obligatoire | Le dernier jour de la période, dans le même exercice. |

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

## Voir aussi

- [Connecter un assistant](https://ocost.io/docs/fr/mcp.md): Connecter un assistant au serveur MCP (https://api.ocost.io/public/mcp, les mêmes clés) : Claude Code, Claude Desktop, Cursor, claude.ai et ChatGPT par OAuth, et tout client.
- [Clés et autorisations](https://ocost.io/docs/fr/authentication.md): Les clés d'API : comment une requête en porte une, leur renouvellement, leurs autorisations et les refus.
- [Le document](https://ocost.io/docs/fr/document.md): Le schéma ocost.document.v1 dans les termes de l'EN 16931 (transposable en UBL et CII) : un exemple, type et sens, sources, contrôles, versions, et chaque champ et chaque valeur.
- Sur ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
