BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_provision_account

Idempotent

Provisions a BeeL account with an optional holder and tax profile, making it ready to invoice. Returns a single-use claim token for the holder to set a password and take ownership.

Instructions

Provisions a new account on BeeL and, when it is born with a holder, returns a single-use claim_token to deliver so they can set a password and take ownership.

email: send it to create the account with a holder. Omit it and the account is created with no person at all, no person_id and no claim_token; a holder can be added later with POST /v1/accounts/{account_id}/claim-tokens.
tax_profile: send it and the account comes back ready to invoice, with its NIF, default invoice series and VeriFactu configuration set up and its company_id in the response. Omit it and the account stays empty until its holder registers a NIF.
access_level: the access you retain over the account. Defaults to NONE; OPERATE requires a tax_profile.
external_ref: the idempotency key. Resending the same one returns the existing account rather than creating a second.
Entitlement: requires manage_accounts.

Reactivation

If you previously ended your management of this account (DELETE /v1/accounts/{account_id}/management) and its holder has not claimed it yet, provisioning the same email reactivates that account instead of creating a new one. The same account, holder, NIFs and invoices come back under your management, with the external_ref and access_level of this request, and it counts towards your billable usage again. Once the holder has claimed the account it is theirs, and only they can grant you access again.

Endpoint: POST /v1/accounts

Input Schema

TableJSON Schema

Name	Required	Description	Default
`body`	Yes
`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.

Changed25 schema fields changedv0.5.0Aug 30, 2026

changedInput schema / $defs / AccessLevel / description

Previous value: -"How much access an actor has to an account or a company (NIF). The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf.\n\n`NONE` — no access to the data.\n`VIEW` — read invoices, customers, products, series and fiscal data.\n`OPERATE` — everything in `VIEW`, plus creating and editing them. Issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see `/v1/accounts/{account_id}/companies/{company_id}/representation`).\n\nAccess level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it."New value: +"How much access an actor has to an account or a company. The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf.\n\n`NONE` — no access to the data.\n`VIEW` — read invoices, customers, products, series and fiscal data.\n`OPERATE` — everything in `VIEW`, plus creating and editing them. Issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see `/v1/accounts/{account_id}/companies/{company_id}/representation`).\n\nAccess level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it."

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"
```
removedInput schema / $defs / EntityType / example
```
Removed value: -"INDIVIDUAL"
```
removedInput schema / $defs / Language / example
```
Removed value: -"es"
```
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"
```
addedInput schema / $defs / ProvisionAccountRequest / additionalProperties
```
Added value: +false
```

changedInput schema / $defs / ProvisionAccountRequest / properties / tax_profile / description

Previous value: -"Optional fiscal identity. When present, the account is created **ready to invoice** in one call: its NIF profile, a default invoice series and VeriFactu config are set up atomically, and the response returns `company_id` (the value for the `BeeL-Active-Company` header when issuing invoices). Omit it to create an empty account the holder completes on claim. **Required when `access_level` is `OPERATE`** (issuing on their behalf needs a NIF) — else `422`."New value: +"Optional fiscal identity. When present, the account is created **ready to invoice** in one call: its company record, a default invoice series and VeriFactu config are set up atomically, and the response returns `company_id` (the value for the `BeeL-Active-Company` header when issuing invoices). Omit it to create an empty account the holder completes on claim. **Required when `access_level` is `OPERATE`** (issuing on their behalf needs a NIF) — else `422`."

addedInput schema / $defs / ProvisionTaxProfile / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / RegimeKey / example
```
Removed value: -"01"
```
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.7/5.0

Behavior5/5

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

Beyond the idempotentHint annotation, the description discloses substantial behavioral detail: idempotency via external_ref, no-person account creation, atomic tax-profile setup, reactivation after ended management, claim-gating of ownership, and the manage_accounts entitlement. This far exceeds what annotations alone provide and never contradicts them.

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 well-structured: a crisp opening sentence, scannable parameter bullets, and a dedicated Reactivation section. It front-loades the most important behavioral facts and keeps every section purposeful despite the detail.

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 provisioning operation with optional email, tax_profile, and access control, the description covers the essential scenarios, side effects, idempotency behavior, and ownership transfer. Even without an output schema, it discloses the critical response fields (claim_token, company_id) and the main edge case (reactivation). Nothing essential for an agent to call it correctly is missing.

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?

With only 50% schema description coverage, the tool description compensates by explaining the behavioral meaning of email, tax_profile, access_level, and external_ref — not just their types. The top-level idempotency_key parameter is left to the schema, but the description adds enough semantic value to make parameter intent clear.

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 uses a specific verb and resource — "Provisions a new account on BeeL" — and immediately names the key outcome (a single-use claim_token when created with a holder). It clearly distinguishes itself from sibling account-management tools by focusing on the provisioning action and endpoint.

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

Usage Guidelines4/5

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

The description gives clear conditional guidance: when to send email, when to include tax_profile, when OPERATE requires it, and how external_ref drives idempotent behavior. It also names an explicit alternative (POST /v1/accounts/{account_id}/claim-tokens) for adding a holder later, though it does not enumerate exclusions versus every sibling.

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

Deploy Server