BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_get_invoice_preview

Read-onlyIdempotent

Returns a temporary pre-signed URL to a WebP preview image of an invoice for inline rendering, using a cached image that expires in five minutes.

Instructions

Returns a temporary pre-signed URL to a preview image (WebP) of the invoice, suitable for inline rendering. The image is generated and cached on first request, so a later call returns the cached image. The URL expires in five minutes and only allows GET.

The image of an issued invoice is taken from its stored PDF, the one delivered. While that PDF does not exist yet — right after issuing (whether or not the invoice goes through VeriFactu, since the PDF is generated asynchronously) or, for a VeriFactu invoice specifically, while it waits for the QR of its registration — the answer is 202, as for the PDF download.

BeeL API endpoint: GET /v1/companies/{company_id}/invoices/{invoice_id}/preview (reference: https://docs.beel.es)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company_id": "<company_id>",
      "invoice_id": "<invoice_id>"
    },
    "name": "beel_get_invoice_preview"
  }
}

Input Schema

Name	Required	Description	Default
`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.
`invoice_id`	Yes	Invoice ID

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.10.0Nov 5, 2026
- addedInput schema / properties / invoice_id / type
```
Added value: +"string"
```

Changed3 schema fields changedv0.5.0Aug 30, 2026

removedInput schema / $defs / UUID / example

Removed value: -"550e8400-e29b-41d4-a716-446655440000"

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.4/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, and the description still adds substantial behaviour beyond them: the image is generated and cached on first request, subsequent calls hit the cache, the URL expires in five minutes, and the URL only permits GET. It also documents the 202 in-progress semantics and the async PDF dependency, which an agent cannot infer from structured fields.

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?

Front-loaded with the return value and format, then the caching/expiry behaviour, then the 202 edge case — a logical order with no filler sentences. The trailing API-endpoint and docs-reference line is meta-information rather than invocation guidance, a minor cost against an otherwise tight description.

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?

With no output schema, the description carries the return-value burden and does so fully: payload is a pre-signed URL, format is WebP, lifetime is five minutes, method is GET-only, and 202 signals not-yet-available. Combined with the parameter schema, an agent has everything needed to call and interpret the result.

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

Parameters3/5

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

Schema description coverage is 100%, and the company_id description already carries the important auth/scoping semantics (403 for unreachable or non-existent companies, header ignored). The description adds nothing about either parameter, so the baseline 3 applies.

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?

States a specific verb and resource ('Returns a temporary pre-signed URL to a preview image (WebP) of the invoice') plus the format and intended use ('suitable for inline rendering'), which cleanly separates it from the PDF-download sibling. An agent can identify the tool without opening the schema.

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?

Gives clear context for use (inline rendering of an issued invoice) and explains the important edge case: a 202 is returned right after issuing, or for VeriFactu invoices awaiting their registration QR, mirroring the PDF download behaviour. It implies the PDF sibling as the alternative for document delivery but never names beel_get_invoice_pdf explicitly as the when-to-use-this-instead routing rule.

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

Deploy Server