BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_create_invoice

Idempotent

Creates Spanish invoices for your company as editable drafts or issued directly, with AEAT VeriFactu compliance and support for standard, simplified, corrective, and proforma types.

Instructions

Creates an invoice for this company. The issuer data comes from the company in the path, and the document is created as a draft unless you ask for it to be issued.

Issuing: options.issue_directly numbers and issues the invoice in the same call. Submission to the AEAT is asynchronous, so verifactu.submission_status comes back as PENDING: a 2xx means the invoice was accepted for submission, not that the AEAT has registered it.
Document type: type chooses the document. A PROFORMA is non-fiscal — it is born ACTIVE, numbered PRO-... from its own non-fiscal series, and ignores issue_directly.
Related: to copy an existing invoice into a new draft, use POST …/invoices/derivations, which carries neither type, nor recipient, nor lines.

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

⚠️ Fiscal guardrails — read before calling:

How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types)
How a line states its price, and which field combinations are rejected. (resource: beel://guardrails/invoice-lines)
What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys)
Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)
Why an issued invoice may never reach AEAT, and how to tell before issuing. (resource: beel://guardrails/verifactu-gates)
How invoice numbers are formed, and why numbering can never be rewritten. (resource: beel://guardrails/series-and-numbering)

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.
`wait_for_pdf`	No	Same flag as `options.wait_for_pdf`. Only applies when the invoice is issued in this call (`options.issue_directly: true`).
`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.

Changed63 schema fields changedv0.5.0Aug 30, 2026

addedInput schema / $defs / Address / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / Address / properties / city / example
```
Removed value: -"Madrid"
```
removedInput schema / $defs / Address / properties / country / example
```
Removed value: -"España"
```
removedInput schema / $defs / Address / properties / country_code / example
```
Removed value: -"ES"
```
removedInput schema / $defs / Address / properties / door / example
```
Removed value: -"A"
```
removedInput schema / $defs / Address / properties / floor / example
```
Removed value: -"2º A"
```
removedInput schema / $defs / Address / properties / number / example
```
Removed value: -"123"
```
removedInput schema / $defs / Address / properties / postal_code / example
```
Removed value: -"28001"
```
removedInput schema / $defs / Address / properties / province / example
```
Removed value: -"Madrid"
```
removedInput schema / $defs / Address / properties / street / example
```
Removed value: -"Calle Mayor, 123"
```
addedInput schema / $defs / CreateInvoiceRequest / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / CreateInvoiceRequest / example

Removed value: -{
-  "due_date": "2025-02-14",
-  "issue_date": "2025-01-15",
-  "lines": [
-    {
-      "description": "Web application development - Sprint 1",
-      "irpf_rate": 15,
-      "main_tax": {
-        "percentage": 21,
-        "regime_key": "01",
-        "type": "IVA"
-      },
-      "quantity": 40,
-      "unit": "hours",
-      "unit_price": 50
-    }
-  ],
-  "metadata": {
-    "client_reference": "REF-2025-001",
-    "project_code": "PROJ-123"
-  },
-  "notes": "Payment by bank transfer. Includes technical support for 30 days.",
-  "options": {
-    "issue_directly": true,
-    "send_automatically": false,
-    "verifactu_enabled": false,
-    "wait_for_pdf": false
-  },
-  "payment_info": {
-    "iban": "ES9121000418450200051332",
-    "method": "BANK_TRANSFER",
-    "payment_term_days": 30
-  },
-  "recipient": {
-    "customer_id": "4f244735-980b-8d9c-80e8-6331fa0b1958"
-  },
-  "series_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "type": "STANDARD"
-}

removedInput schema / $defs / CreateInvoiceRequest / properties / due_date / example
```
Removed value: -"2025-02-14"
```

removedInput schema / $defs / CreateInvoiceRequest / properties / lines / example

Removed value: -[
-  {
-    "description": "Web application development - Sprint 1",
-    "discount_percentage": 0,
-    "irpf_rate": 15,
-    "main_tax": {
-      "percentage": 21,
-      "regime_key": "01",
-      "type": "IVA"
-    },
-    "quantity": 40,
-    "unit": "hours",
-    "unit_price": 50
-  }
-]

addedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / description / example
```
Removed value: -"Web application development - Sprint 1"
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / discount_percentage / example
```
Removed value: -10
```

changed

Input schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / equivalence_surcharge_rate / description

Previous value: -"Equivalence surcharge rate for this line.\n\n**Default behaviour:** if omitted and the company has\n`apply_equivalence_surcharge: true` in its tax configuration,\nthe line inherits the surcharge — and its percentage is a legal\nfunction of the line's VAT rate, not the configured default:\n21 ↔ 5.2, 10 ↔ 1.4, 5 ↔ 0.625, 4 ↔ 0.5 (the pairs enumerated by\n`EquivalenceSurchargePercentage`). A company configured with\n`default_equivalence_surcharge: 5.2` therefore produces 1.4 on a\n10% line, not 5.2.\n\n**The inheritance also rewrites the line's `regime_key` from `01`\nto `18`** (special regime for equivalence surcharge). This is\ndeliberate: a surcharge and general regime `01` are fiscally\nincoherent, so the line comes back as `18` even if `01` was sent.\n\nTo issue a line **without** surcharge under such a company, send\n`equivalence_surcharge_rate: 0` explicitly — exactly as with\n`irpf_rate`: the `01` regime key is then respected and no\nsurcharge is applied. Sending an explicit rate greater than 0\ntogether with `regime_key: \"01\"` is **rejected** with\n`RECARGO_REQUIRES_REGIME_RE`.\n"New value: +"Equivalence surcharge rate for this line.\n\n**Default behaviour:** if omitted and the company has\n`apply_equivalence_surcharge: true` in its tax configuration,\nthe line inherits the surcharge — and its percentage is a legal\nfunction of the line's VAT rate, not the configured default:\n21 ↔ 5.2, 10 ↔ 1.4, 5 ↔ 0.625, 4 ↔ 0.5 (the pairs enumerated by\n`EquivalenceSurchargePercentage`). A company configured with\n`default_equivalence_surcharge: 5.2` therefore produces 1.4 on a\n10% line, not 5.2.\n\n**The inheritance also rewrites the line's `regime_key` from `01`\nto `18`** (special regime for equivalence surcharge). This is\ndeliberate: a surcharge and general regime `01` are fiscally\nincoherent, so the line comes back as `18` even if `01` was sent.\n\nTo issue a line **without** surcharge under such a company, send\n`equivalence_surcharge_rate: 0` explicitly — exactly as with\n`irpf_rate`: the `01` regime key is then respected and no\nsurcharge is applied. Sending an explicit rate greater than 0\ntogether with `regime_key: \"01\"` is **not** rejected: the very\nsame rewrite applies and the line comes back as `18`.\n\n**Any other regime with a surcharge is rejected** with\n`422 SURCHARGE_REQUIRES_REGIME`. Only the general regime `01`\n**rewrites**; REBU (`03`), exports (`02`), OSS (`17`)… never do,\nbecause a surcharge under them is fiscally invalid — an error to\nsurface, not a shorthand to normalise.\n"

removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / exemption_reason / $ref
```
Removed value: -"#/$defs/ExemptionReason"
```
addedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / exemption_reason / anyOf
```
Added value: +[
+  {
+    "$ref": "#/$defs/ExemptionReason"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / quantity / example
```
Removed value: -40
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / total_excluding_tax / example
```
Removed value: -1
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / total_including_tax / example
```
Removed value: -100
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / unit / example
```
Removed value: -"hours"
```
removedInput schema / $defs / CreateInvoiceRequest / properties / lines / items / properties / unit_price / example
```
Removed value: -50
```

removedInput schema / $defs / CreateInvoiceRequest / properties / notes / example

Removed value: -"Payment by bank transfer. Includes technical support for 30 days."

removedInput schema / $defs / CreateInvoiceRequest / properties / operation_date / example
```
Removed value: -"2025-01-10"
```
removedInput schema / $defs / CreateInvoiceRequest / properties / series_id / example
```
Removed value: -"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```
removedInput schema / $defs / CreateInvoiceRequest / properties / valid_until / example
```
Removed value: -"2025-02-28"
```
removedInput schema / $defs / Email / example
```
Removed value: -"user@example.com"
```
addedInput schema / $defs / EmailConfiguration / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / EmailConfiguration / example

Removed value: -{
-  "cc": [
-    "accounting@example.com"
-  ],
-  "message": "Please find attached the requested invoice. We remain at your disposal for any clarification.",
-  "recipients": [
-    "client@example.com"
-  ],
-  "subject": "Invoice 2025/0001 - Development services"
-}

removedInput schema / $defs / EmailConfiguration / properties / cc / example
```
Removed value: -[
-  "copy@example.com"
-]
```

removedInput schema / $defs / EmailConfiguration / properties / message / example

Removed value: -"Dear customer, please find attached the invoice for the services provided. Thank you for your trust."

removedInput schema / $defs / EmailConfiguration / properties / recipients / example
```
Removed value: -[
-  "client@example.com"
-]
```
removedInput schema / $defs / EmailConfiguration / properties / subject / example
```
Removed value: -"Invoice 2025/0001 - Web development services"
```
removedInput schema / $defs / EquivalenceSurchargePercentage / example
```
Removed value: -5.2
```
removedInput schema / $defs / ExemptionReason / example
```
Removed value: -"EXENTA_ART_20"
```
removedInput schema / $defs / ExternalRef / example
```
Removed value: -"ORD-2025-0042"
```

removedInput schema / $defs / IBAN / example

Removed value: -"ES1234567890123456789012"

removedInput schema / $defs / InvoiceLineType / example
```
Removed value: -"NORMAL"
```

removedInput schema / $defs / InvoiceMetadata / example

Removed value: -{
-  "external_order_id": "ORD-2025-0042",
-  "project_code": "PROJ-123",
-  "tenant": "acme"
-}

addedInput schema / $defs / InvoiceProcessingOptions / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / InvoiceProcessingOptions / example

Removed value: -{
-  "issue_directly": true,
-  "send_automatically": false,
-  "verifactu_enabled": false,
-  "wait_for_pdf": false
-}

removedInput schema / $defs / IrpfPercentage / example
```
Removed value: -15
```
addedInput schema / $defs / PaymentInfo / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / PaymentInfo / properties / payment_term_days / example
```
Removed value: -30
```
removedInput schema / $defs / PaymentMethod / example
```
Removed value: -"BANK_TRANSFER"
```
removedInput schema / $defs / Phone / example
```
Removed value: -"+34 612 345 678"
```
addedInput schema / $defs / Recipient / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / Recipient / example

Removed value: -{
-  "customer_id": "4f244735-980b-8d9c-80e8-6331fa0b1958"
-}

removedInput schema / $defs / Recipient / properties / customer_id / example
```
Removed value: -"4f244735-980b-8d9c-80e8-6331fa0b1958"
```
removedInput schema / $defs / Recipient / properties / legal_name / example
```
Removed value: -"Tech Solutions SL"
```
removedInput schema / $defs / Recipient / properties / nif / example
```
Removed value: -"B12345674"
```
removedInput schema / $defs / Recipient / properties / trade_name / example
```
Removed value: -"TechSol"
```
removedInput schema / $defs / RegimeKey / example
```
Removed value: -"01"
```
removedInput schema / $defs / SWIFT / example
```
Removed value: -"ABCDESMMXXX"
```
addedInput schema / $defs / TaxInfo / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / TaxInfo / example

Removed value: -{
-  "percentage": 21,
-  "regime_key": "01",
-  "type": "IVA"
-}

removedInput schema / $defs / TaxInfo / properties / percentage / example
```
Removed value: -21
```
removedInput schema / $defs / TaxType / example
```
Removed value: -"IVA"
```
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.7/5.0

Behavior5/5

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

Beyond what annotations provide, the description discloses critical asynchronous behavior: AEAT submission is async, `verifactu.submission_status` returns `PENDING`, and a 2xx only means accepted for submission, not registered. It also explains that PROFORMA is non-fiscal, always active, numbered from its own series, and ignores `issue_directly`. This is exactly the kind of behavioral context an agent cannot infer from schema or annotations.

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 description is well-structured and front-loaded: the core operation comes first, followed by bullets for issuing, document type, related endpoints, and guardrails. The guardrail section is long but each item is relevant and task-critical for a fiscally complex operation. It earns its length, though it could be slightly tightened.

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 complex mutation with no output schema, the description provides the endpoint, draft/issue state machine, async submission caveat, related-alternative routing, and guardrail pointers. It does not fully describe the response shape beyond `verifactu.submission_status`, which is a minor gap given the absence of an output schema. Overall, an agent has enough context to call this tool correctly.

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?

Schema description coverage is 75%, so the baseline is already high. The description adds real meaning to `type` by explaining PROFORMA's non-fiscal lifecycle and to `options.issue_directly` by clarifying numbering, issuing, and async submission behavior. It does not add much about `recipient` or `lines`, but the schema already documents those extensively.

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 first sentence states a specific verb and resource: "Creates an invoice for this company." It then clarifies the default draft behavior and explicitly routes copying an existing invoice to the derivations endpoint, distinguishing this tool from sibling invoice-creation tools. The endpoint is also included, removing ambiguity.

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

Usage Guidelines5/5

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

The description gives concrete when-to-use guidance: drafts by default, `issue_directly` to number and issue, PROFORMA behavior, and an explicit alternative for copying invoices via `POST …/invoices/derivations`. It also tells the agent to consult the listed guardrail resources before calling, which is practical and actionable.

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_invoice

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools