BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_create_company

Idempotent

Create a company under an account, register its NIF, and optionally activate it with default invoice series in the AEAT environment.

Instructions

Creates a company under the account the request resolves to. The NIF is registered in the name of that account's holder, never in the name of the caller.

activate: unless it is false, the company is switched on in aeat_environment and its three default invoice series (ordinary, simplified, corrective) are seeded there. This endpoint never switches an existing company on: that is POST /v1/companies/{company_id}/activations.
numbering: decides the code, format, counter reset and starting number those series are born with. Only accepted when the request activates the company.
Billing: no charge is ever started here. Creating a production NIF on an account without billing is rejected with 402, and no checkout is opened.
Duplicates: a NIF that already exists in the account is rejected with 409, and the response carries the existing error.details.company_id.

Endpoint: POST /v1/accounts/{account_id}/companies

⚠️ Fiscal guardrails — read before calling:

Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)
Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)
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
`account_id`	Yes	Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a `403` is returned when you do not reach it, the same response an account that does not exist gets.
`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.

Changed34 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 / CompanyNumbering / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / CompanyNumbering / properties / initial_number / example
```
Removed value: -151
```
addedInput schema / $defs / CompanySeriesNumbering / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / CompanySeriesNumbering / properties / initial_number / example
```
Removed value: -40
```
addedInput schema / $defs / CreateCompanyRequest / additionalProperties
```
Added value: +false
```

changedInput schema / $defs / CreateCompanyRequest / properties / activate / description

Previous value: -"Whether to **switch the company on** in `aeat_environment` as part of this call.\n\nCreating a company and activating it are two different acts. The NIF profile is free\nand always creatable; the activation is what seeds the invoice series, registers the\nNIF and — in `PROD` — is what gets billed.\n\n* `true` (default) — unchanged behaviour: the company is created and switched on in\n  `aeat_environment`, with its default series seeded there.\n* `false` — only the NIF profile is created. The company is switched on nowhere, has\n  no series and cannot issue yet; `aeat_environment` is ignored. Activate it later\n  with `POST /v1/companies/{company_id}/activations`, which is also\n  the only door that opens a Stripe Checkout when the account has no card on file.\n\nSeries numbering travels with the activation that seeds it: a request with\n`activate: false` and a `numbering` block that asks for anything is rejected with\n`422` `NUMBERING_REQUIRES_ACTIVATION` — the later activation door does not accept\nnumbering, so silently accepting it here would discard it forever. Either drop the\n`numbering` block or activate a mode in the same call.\n"New value: +"Whether to **switch the company on** in `aeat_environment` as part of this call.\n\nCreating a company and activating it are two different acts. The company record is free\nand always creatable; the activation is what seeds the invoice series, registers the\nNIF and — in `PROD` — is what gets billed.\n\n* `true` (default) — unchanged behaviour: the company is created and switched on in\n  `aeat_environment`, with its default series seeded there.\n* `false` — only the company record is created. It is switched on nowhere, has\n  no series and cannot issue yet; `aeat_environment` is ignored. Activate it later\n  with `POST /v1/companies/{company_id}/activations`, which is also\n  the only door that opens a Stripe Checkout when the account has no card on file.\n\nSeries numbering travels with the activation that seeds it: a request with\n`activate: false` and a `numbering` block that asks for anything is rejected with\n`422` `NUMBERING_REQUIRES_ACTIVATION` — the later activation door does not accept\nnumbering, so silently accepting it here would discard it forever. Either drop the\n`numbering` block or activate a mode in the same call.\n"

removedInput schema / $defs / CreateCompanyRequest / properties / default_irpf_rate / example
```
Removed value: -15
```
removedInput schema / $defs / CreateCompanyRequest / properties / legal_form / example
```
Removed value: -"SL"
```
removedInput schema / $defs / CreateCompanyRequest / properties / legal_name / example
```
Removed value: -"Mi Empresa SL"
```
removedInput schema / $defs / CreateCompanyRequest / properties / nif / example
```
Removed value: -"B12345674"
```
removedInput schema / $defs / CreateCompanyRequest / properties / trade_name / example
```
Removed value: -"Mi Empresa"
```
removedInput schema / $defs / EntityType / example
```
Removed value: -"INDIVIDUAL"
```
removedInput schema / $defs / Environment / example
```
Removed value: -"PROD"
```
addedInput schema / $defs / LegalRepresentative / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / LegalRepresentative / properties / full_name / example
```
Removed value: -"María García López"
```
removedInput schema / $defs / LegalRepresentative / properties / nif / example
```
Removed value: -"12345678A"
```
removedInput schema / $defs / RegimeKey / example
```
Removed value: -"01"
```
removedInput schema / $defs / SeriesCode / example
```
Removed value: -"FAC"
```
removedInput schema / $defs / SeriesFormat / example
```
Removed value: -"{CODIGO}-{YYYY}-{NUM:4}"
```
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
```

First observedv0.3.1Aug 25, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations, the description discloses key behaviors: the NIF is registered in the account holder's name, no charge is started, a production NIF without billing is rejected with 402, duplicates produce 409 with the existing company id, and activate:false creates a record with no series. These are material side effects and error conditions that an agent needs to invoke the tool safely.

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

Conciseness5/5

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

The description is long but every section earns its place: the main behavior is front-loaded, then activation, numbering, billing, duplicates, and guardrails are each given focused bullet treatment. The structured layout makes dense fiscal information scannable rather than opaque.

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

Completeness5/5

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

For a complex creation endpoint with no output schema, the description covers invocation, side effects, failure modes, idempotency hints, and related endpoints. It also links to the guardrails an agent should consult before creating a company. The provided information is sufficient for an agent to decide and execute the call 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?

The input schema already covers activate, numbering, account_id, and idempotency_key in detail, so the description does not need to repeat them. It adds complementary meaning around nif duplicates, account ownership semantics, and the fact that aeat_environment is ignored when activate is false. This is meaningful but not exhaustive parameter-level guidance, hence slightly above baseline.

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 company under the account the request resolves to.' It also names the endpoint and explicitly distinguishes itself from activation via 'This endpoint never switches an existing company on: that is POST /v1/companies/{company_id}/activations.' This makes it unambiguous among the many beel_create_* siblings.

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 explicit when-to-use guidance and names the alternative for activating existing companies. It also explains when the tool is not appropriate, e.g., activation must go through POST /v1/companies/{company_id}/activations, and 'numbering' is rejected when activate is false. The guardrail links and pointer to beel_docs_search further support correct usage decisions.

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_company

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools