BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_create_recurring_invoice

Idempotent

Set up monthly recurring invoices by defining lines, recipient, series, and payment once; the template then generates invoices automatically on the chosen day, with optional draft preview and VeriFactu compliance.

Instructions

Creates a recurring invoice template under this company: the invoice data it repeats (lines, recipient, series, payment) plus the recurrence that drives it.

Cadence: generation runs monthly on day_of_month, from start_date until end_date if one is given. frequency only accepts MONTHLY.
start_date in the past: accepted and stored as sent, but it never anchors generation backwards. next_generation moves to the first upcoming day_of_month, and the missed periods are not generated.
preview_days: how many days before the emission date the invoice is created as a draft for review. 0, the default, means immediate emission.
VeriFactu: omitting verifactu_enabled applies the company's declared preference (apply_by_default, resolving to false when the company has no VeriFactu configuration). The resolved value is frozen into the template at creation time, so changing that preference later does not alter templates that already exist.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices

⚠️ Fiscal guardrails — read before calling:

How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types)
What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys)

For the exhaustive rules and worked examples, call beel_docs_search.

Input Schema

TableJSON Schema

Name	Required	Description
`body`	Yes
`company_id`	Yes	Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
`idempotency_key`	No	Optional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.5.0Aug 30, 2026

addedInput schema / $defs / CreateRecurringInvoiceRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / CreateRecurringInvoiceRequest / properties / payment_method / allOf
```
Removed value: -[
-  {
-    "$ref": "#/$defs/PaymentMethod"
-  }
-]
```

addedInput schema / $defs / CreateRecurringInvoiceRequest / properties / payment_method / anyOf

Added value: +[
+  {
+    "allOf": [
+      {
+        "$ref": "#/$defs/PaymentMethod"
+      }
+    ]
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / $defs / ExemptionReason / example
```
Removed value: -"EXENTA_ART_20"
```
removedInput schema / $defs / PaymentMethod / example
```
Removed value: -"BANK_TRANSFER"
```
addedInput schema / $defs / RecurringLineRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / RecurringLineRequest / properties / exemption_reason / $ref
```
Removed value: -"#/$defs/ExemptionReason"
```

addedInput schema / $defs / RecurringLineRequest / properties / exemption_reason / anyOf

Added value: +[
+  {
+    "$ref": "#/$defs/ExemptionReason"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / company_id / description

Previous value: -"NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed."New value: +"Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed."

First observedv0.3.1Aug 25, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses several non-obvious behaviors far beyond what annotations provide: monthly-only frequency, no backward generation from past start dates, preview_days semantics, and the freezing of the resolved VeriFactu preference into the template. It also points to fiscal guardrails that must be read before calling. No contradiction with the annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The key purpose is front-loaded, and the supporting details are organized into scannable bullets. Some content repeats schema descriptions (notably start_date and verifactu_enabled), but the overall length is justified by the complexity of recurrence behavior and the fiscal guardrail warnings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no output schema, the description covers the essential operational context: what is created, when invoices are generated, how past dates behave, what preview_days means, and how VeriFactu defaults are resolved. It also routes the agent to guardrail resources and beel_docs_search for exhaustive rules, which closes the remaining knowledge gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema already describes several parameters, the description adds meaningful semantics for day_of_month, frequency, start_date, preview_days, and verifactu_enabled, including the freezing behavior and the monthly-only constraint. It does not cover every parameter, but the schema descriptions fill most remaining gaps, so this is a solid compensating effort.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Creates a recurring invoice template under this company'. It then clarifies what the template contains (lines, recipient, series, payment) and that it is a template, not the invoice itself, which distinguishes it from siblings like beel_create_invoice or beel_generate_recurring_invoice_now.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong contextual guidance about cadence, past start dates, preview_days, and VeriFactu defaults, which helps an agent decide whether this tool fits the scenario. However, it never explicitly contrasts this tool with alternatives such as beel_generate_recurring_invoice_now or beel_create_invoice, so the when-not-to-use guidance is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

beel_create_recurring_invoice

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools