# Tools & prompts

The tools the BeeL. MCP server exposes and what they do not cover yet, the guided workflow prompts, and the inline invoice PDF viewer.

Through the BeeL. MCP server your assistant can issue and manage invoices, customers, products, series, recurring invoices and NIFs, run your account's members and webhooks, and read your fiscal data. On top of that there are a few **helper tools** and **guided prompts** that keep fiscal steps in the right order.

The tools are derived from the API contract, so each one takes the same fields as the operation behind it. They cover most of the API, not all of it: some operations are left out on purpose and a few newer ones are not exposed yet. See [what the tools don't cover](#what-the-tools-dont-cover). This page describes version **0.5.0** of the server.

<Callout type="info">
  Tools are named `beel_<action>` and grouped by resource. Each needs specific **scopes**; the assistant can only use a tool if the scopes you approved on the consent screen cover it.
</Callout>

## Helper tools

A few tools help the assistant orient itself before it acts:

| Tool | Description |
| --- | --- |
| `beel_get_setup_status` | One-call checklist of every NIF's readiness with a recommended next action — the fastest way to see what's missing. |
| `beel_docs_search` | Search these docs from inside the client. |
| `beel_docs_get` | Read a documentation page in full. |
| `beel_docs_list` | List the available documentation pages. |
| `beel_rules_list` | List the [fiscal rules](/rules), one line each, filtered by domain, responsibility (`enforced_by`), severity or keywords. Called with no filters it also lists the domains. |
| `beel_rules_get` | Read one fiscal rule by id (statement, legal basis, error codes, examples, related rules), or every rule that cites an error code. |

When an API call fails with an error code that a rule cites, the error the assistant gets back names that rule. For the other ways to use the rules, see [Use the rules in your tools](/rules#use-the-rules-in-your-tools).

## Guided prompts

Prompts are templates you invoke like a command; they seed the conversation with the correct **order of operations** so the assistant doesn't skip a fiscal step.

| Prompt | What it does |
| --- | --- |
| `issue-invoice` | Issue an invoice: F1 vs F2, validate the NIF, set regime keys, clear the VeriFactu gates. |
| `fix-invoice` | Fix an issued invoice the right way: void vs corrective invoice (R1–R5). |
| `onboard-nif` | Get a NIF ready to issue Live end to end: readiness → default series → VeriFactu → payments → first Test invoice. |
| `setup-representation` | Set up the AEAT fiscal representation (apoderamiento) a NIF needs for VeriFactu — resolves the `NIF_REPRESENTATION_REQUIRED` blocker. |
| `invite-member` | Invite a collaborator (such as an accounting firm) or teammate and grant the right role, account-wide or per-NIF. |
| `connect-payments` | Connect Stripe to a NIF or account-wide, and verify it is active. |
| `upgrade-integration` | Bring an existing BeeL. API integration up to current best practices. |

## Inline invoice PDF

When the assistant fetches an invoice PDF, the BeeL. MCP server returns it as an **MCP App**: a client that supports MCP UI (such as Claude) renders the invoice **inline in the chat** as an embedded viewer, instead of a bare download link — so you review the document without leaving the conversation.

## Tool catalogue

The API tools, grouped by resource, with the scopes each one needs.

<Accordions type="single">

<Accordion title="AccountCompanies (3)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_company` | Create a company | `companies:write` |
| `beel_list_companies` | List the companies of an account | `companies:list` |
| `beel_list_stats` | Get invoice stats per company | `companies:list` |

</Accordion>

<Accordion title="AccountEmails (3)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_email_delivery` | Get an email of the history | `emails:read` |
| `beel_get_email_delivery_indicators` | Get the email indicators of several entities | `emails:read` |
| `beel_list_email_deliveries` | List the email history | `emails:read` |

</Accordion>

<Accordion title="AccountRequestLogs (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_request_log` | Get an API request log detail | `logs:read` |
| `beel_list_request_logs` | List API request logs | `logs:read` |

</Accordion>

<Accordion title="AccountWebhooks (9)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_webhook_subscription` | Create a webhook subscription | `webhooks:write` |
| `beel_delete_webhook_subscription` | Delete a webhook subscription | `webhooks:write` |
| `beel_get_webhook_subscription` | Get a webhook subscription | `webhooks:read` |
| `beel_list_webhook_deliveries` | List the delivery attempts of a webhook | `webhooks:read` |
| `beel_list_webhook_subscriptions` | List the webhook subscriptions | `webhooks:read` |
| `beel_patch_webhook_subscription` | Update a webhook subscription | `webhooks:write` |
| `beel_retry_webhook_delivery` | Retry a failed webhook delivery | `webhooks:write` |
| `beel_rotate_webhook_secret` | Rotate the signing secret of a webhook | `webhooks:write` |
| `beel_test_webhook_subscription` | Send a test event to a webhook endpoint | `webhooks:write` |

</Accordion>

<Accordion title="Accounts (5)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_change_managed_access_level` | Change your access over a managed account | `accounts:write` |
| `beel_create_claim_token` | Issue a claim token | `accounts:write` |
| `beel_end_management` | End your management of an account | `accounts:write` |
| `beel_get_usage` | Get your provisioning usage | `accounts:read` |
| `beel_provision_account` | Provision an account | `accounts:write` |

</Accordion>

<Accordion title="Company (4)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_delete_company` | Delete a company | `companies:write` |
| `beel_get_company` | Get a company | `companies:read` |
| `beel_get_issuing_readiness` | Get the issuing readiness of a company | `companies:read` |
| `beel_patch_company` | Update a company | `companies:write` |

</Accordion>

<Accordion title="CompanyActivations (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_activate_company` | Switch a company on | `companies:write` |
| `beel_deactivate_company` | Switch a company off | `companies:write` |

</Accordion>

<Accordion title="CompanyBranding (3)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_delete_company_logo` | Delete the logo of a company | `companies:write` |
| `beel_get_invoice_customization` | Get the invoice customization of a company | `companies:read` |
| `beel_update_invoice_customization` | Update the invoice customization of a company | `companies:write` |

</Accordion>

<Accordion title="CompanyCustomers (7)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_customer` | Create a customer for a company | `customers:write` |
| `beel_create_customers_bulk` | Create several customers of a company | `customers:write` |
| `beel_delete_customer` | Delete a customer of a company | `customers:write` |
| `beel_delete_customers_bulk` | Delete several customers of a company | `customers:write` |
| `beel_get_customer` | Get a customer of a company | `customers:read` |
| `beel_list_customers` | List the customers of a company | `customers:read` |
| `beel_patch_customer` | Update a customer of a company partially | `customers:write` |

</Accordion>

<Accordion title="CompanyFiscalSummary (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_fiscal_summary` | Get the fiscal summary of a company | `invoices:read` |

</Accordion>

<Accordion title="CompanyInvoiceDelivery (5)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_invoice_batch` | Apply one operation to a set of invoices | `invoices:write` |
| `beel_create_invoice_delivery` | Send several invoices in one email | `invoices:write` |
| `beel_get_invoice_pdf` | Get the PDF download URL of an invoice | `invoices:read` |
| `beel_get_invoice_preview` | Get the preview image URL of an invoice | `invoices:read` |
| `beel_send_invoice` | Send an invoice by email | `invoices:write` |

</Accordion>

<Accordion title="CompanyInvoiceLifecycle (7)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_corrective_invoice` | Create a corrective invoice | `invoices:write` |
| `beel_delete_invoice_schedule` | Remove the scheduling of an invoice | `invoices:write` |
| `beel_get_invoice_schedule` | Get the scheduling of an invoice | `invoices:read` |
| `beel_issue_invoice` | Issue an invoice | `invoices:write` |
| `beel_set_invoice_schedule` | Schedule an invoice | `invoices:write` |
| `beel_set_invoice_status` | Set the status of an invoice | `invoices:write` |
| `beel_void_invoice` | Void an issued invoice | `invoices:write` |

</Accordion>

<Accordion title="CompanyInvoices (6)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_invoice` | Create an invoice | `invoices:write` |
| `beel_create_invoice_derivation` | Derive a draft invoice from an existing one | `invoices:write` |
| `beel_delete_invoice` | Delete a draft invoice | `invoices:write` |
| `beel_get_invoice` | Get an invoice | `invoices:read` |
| `beel_list_invoices` | List invoices | `invoices:read` |
| `beel_patch_invoice` | Update an invoice | `invoices:write` |

</Accordion>

<Accordion title="CompanyPaymentConnections (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_initiate_payment_connection` | Open an authorization to connect a payment provider | `payment-connections:write` |
| `beel_list_payment_connections` | List the payment connections of a NIF | `payment-connections:read` |

</Accordion>

<Accordion title="CompanyProducts (7)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_product` | Create a product for a company | `products:write` |
| `beel_create_products_bulk` | Create several products for a company | `products:write` |
| `beel_delete_product` | Delete a product of a company | `products:write` |
| `beel_delete_products_bulk` | Delete several products of a company | `products:write` |
| `beel_get_product` | Get a product of a company | `products:read` |
| `beel_list_products` | List the products of a company | `products:read` |
| `beel_patch_product` | Update a product of a company partially | `products:write` |

</Accordion>

<Accordion title="CompanyProforma (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_convert_proforma_to_invoice` | Convert a proforma into an invoice | `invoices:write` |

</Accordion>

<Accordion title="CompanyRecurringInvoices (11)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_recurring_invoice` | Create a recurring invoice | `invoices:write` |
| `beel_create_recurring_invoice_derivation` | Derive a recurring invoice from an existing invoice | `invoices:write` |
| `beel_delete_recurring_invoice` | Delete a recurring invoice | `invoices:write` |
| `beel_generate_recurring_invoice_now` | Generate an invoice now from a recurring template | `invoices:write` |
| `beel_get_recurring_invoice` | Get a recurring invoice | `invoices:read` |
| `beel_get_recurring_invoice_history` | Get the generation history of a recurring invoice | `invoices:read` |
| `beel_get_recurring_next_occurrence` | Get the next occurrence of a recurring invoice | `invoices:read` |
| `beel_list_recurring_invoices` | List recurring invoices | `invoices:read` |
| `beel_patch_recurring_invoice` | Update a recurring invoice | `invoices:write` |
| `beel_set_recurring_invoice_status` | Set the status of a recurring invoice | `invoices:write` |
| `beel_skip_recurring_invoice` | Skip the next generation of a recurring invoice | `invoices:write` |

</Accordion>

<Accordion title="CompanyRepresentation (4)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_cancel_representation` | Cancel the fiscal representation | `companies:write` |
| `beel_download_representation_document` | Download the representation document | `companies:read` |
| `beel_generate_representation` | Generate the representation document | `companies:write` |
| `beel_get_representation` | Get the fiscal representation | `companies:read` |

</Accordion>

<Accordion title="CompanySeries (8)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_series` | Create an invoice series for a company | `series:write` |
| `beel_delete_series` | Delete an invoice series | `series:write` |
| `beel_ensure_default_series` | Ensure a default series per document type | `series:write` |
| `beel_get_default_series` | Get the default series of a company | `series:read` |
| `beel_get_series` | Get an invoice series | `series:read` |
| `beel_list_series` | List the invoice series of a company | `series:read` |
| `beel_patch_series` | Update an invoice series | `series:write` |
| `beel_set_default_series` | Mark a series as default | `series:write` |

</Accordion>

<Accordion title="CompanyTaxConfiguration (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_tax_configuration` | Get the tax configuration of a company | `configuration:read` |
| `beel_update_tax_configuration` | Update the tax configuration of a company | `configuration:write` |

</Accordion>

<Accordion title="CompanyVeriFactuConfiguration (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_verifactu_configuration` | Get the VeriFactu configuration of a company | `configuration:read` |
| `beel_update_verifactu_configuration` | Update the VeriFactu configuration of a company | `configuration:write` |

</Accordion>

<Accordion title="Identity (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_my_identity` | Get my identity | — |

</Accordion>

<Accordion title="Invitations (4)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_create_invitation` | Create an invitation | `members:write` |
| `beel_delete_invitation` | Revoke an invitation | `members:write` |
| `beel_get_invitation` | Retrieve an invitation | `members:read` |
| `beel_list_invitations` | List the account's invitations | `members:read` |

</Accordion>

<Accordion title="InvoiceCustomization (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_list_invoice_customization_options` | List the invoice PDF templates | `configuration:read` |

</Accordion>

<Accordion title="Me (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_update_me` | Update my preferences | `configuration:write` |

</Accordion>

<Accordion title="Members (7)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_delete_member` | Remove a member from the account | `members:write` |
| `beel_delete_member_grant` | Revoke a member's access to a company | `members:write` |
| `beel_get_member` | Retrieve a member | `members:read` |
| `beel_list_member_grants` | List a member's company grants | `members:read` |
| `beel_list_members` | List the account's members | `members:read` |
| `beel_patch_member` | Change a member's account role | `members:write` |
| `beel_put_member_grant` | Grant a member access to a company | `members:write` |

</Accordion>

<Accordion title="NIF (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_validate_nif` | Validate a NIF against the AEAT register | `nif:validate` |

</Accordion>

<Accordion title="Provisioning (2)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_get_account` | Retrieve a provisioned account | `accounts:read` |
| `beel_list_accounts` | List the accounts you provisioned | `accounts:read` |

</Accordion>

<Accordion title="TaxTypes (1)">

| Tool | Description | Scopes |
| --- | --- | --- |
| `beel_list_tax_types` | List the tax types allowed in Spain | `configuration:read` |

</Accordion>

</Accordions>

## What the tools don't cover

**Left out on purpose.** Operations that move a file, operations that only a signed-in dashboard session can call, and deprecated operations have no tool:

- Downloading several invoice PDFs as a ZIP, exporting invoices to Excel, and the PDF preview of a draft. For a single invoice, `beel_get_invoice_pdf` returns the download URL and the client shows the PDF [inline](#inline-invoice-pdf).
- Uploading a company logo, importing customers or managed accounts from a file, the import templates, and submitting the signed representation document.
- Setting the account owner.

**Not exposed yet.** These operations are in the API but have no tool in this version. Call them [through the API](/api/openapi) or the [Node SDK](/sdks/node) meanwhile:

- Listing the VeriFactu records of an invoice.
- Recurring invoice statistics.
- Updating a payment connection's settings.
- Resolving, discarding and restoring payment events.

<Callout type="warn" title="Payment event tools fail in 0.5.0">
  `beel_list_payment_events`, `beel_get_payment_event`, `beel_retry_payment_event`, `beel_generate_payment_event_draft` and `beel_disconnect_payment_connection` still appear in your client's tool list, but they address a connection by its provider, a route shape the API no longer serves. Every call to them fails. They are left out of the catalogue above. To audit or recover payment events, or to disconnect a connection, use the API or the SDK, which address each connection by its own ID. See [Payment connections](/multi-nif/payment-connections).
</Callout>

## Related

<Related>

- [MCP overview](/mcp) — connect a client and the guardrails
- [CLI](/cli) — the same API from the terminal
- [Node.js SDK](/sdks/node) — for the integration your project ships

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi