BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_create_invitation

DestructiveIdempotent

Create a single-use invitation for a person to join an account with a specific role, returning an acceptance token and ready-to-use invitation URL you deliver or email.

Instructions

Creates a single-use invitation for a person to join the account with the given account_role.

token: the acceptance secret, returned once and never readable again, so deliver it to the invitee. invitation_url is the ready-to-use link built from that same token.
grants: the companies a MEMBER starts with. Omit it, or send [], to invite them with no company access yet; an explicit null is rejected with 422. Grants are only valid for MEMBER, since OWNER and ADMIN reach every company implicitly.
account_role: OWNER cannot be invited. An account has exactly one owner, handed over only through PUT /v1/accounts/{account_id}/owner.
send_email: defaults to false, so BeeL sends no email and you deliver the token or invitation_url yourself. Set it to true to have the invitation emailed to invited_email as well.

BeeL API endpoint: POST /v1/accounts/{account_id}/invitations (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": {
      "account_id": "<account_id>",
      "body": "<body>"
    },
    "name": "beel_create_invitation"
  }
}

Input 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.

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

Changed3 schema fields changedv0.9.0Oct 1, 2026

changedInput schema / $defs / CreateInvitationRequest / properties / grants / description

Previous value: -"Initial grants (only when `account_role` is `MEMBER`). Required: send `[]` to invite with no company access yet (granted later). An explicit `null` is rejected with 400."New value: +"Initial grants (only when `account_role` is `MEMBER`). Omit it, or send `[]`, to invite with no company access yet (granted later). An explicit `null` is rejected with `422` `VALIDATION_ERROR`."

addedInput schema / $defs / CreateInvitationRequest / properties / grants / x-field-extra-annotation
```
Added value: +"@jakarta.validation.constraints.NotNull"
```

changedInput schema / $defs / CreateInvitationRequest / required

Previous value: -[
-  "invited_email",
-  "account_role",
-  "grants"
-]New value: +[
+  "invited_email",
+  "account_role"
+]

Changed5 schema fields changedv0.5.0Aug 30, 2026

changedInput schema / $defs / AccountRole / description

Previous value: -"Who administers the account. Independent of `access_level`, which says how much access someone has to a given company (NIF).\n\n`OWNER` — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with `422 OWNER_ROLE_NOT_ASSIGNABLE`. Ownership moves only through `PUT /v1/accounts/{account_id}/owner`.\n`ADMIN` — everything an `OWNER` can do, except transferring ownership.\n`MEMBER` — no account administration. Access to each company is granted individually and reported as `access_level`; a member only sees the companies granted to them."New value: +"Who administers the account. Independent of `access_level`, which says how much access someone has to a given company.\n\n`OWNER` — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with `422 OWNER_ROLE_NOT_ASSIGNABLE`. Ownership moves only through `PUT /v1/accounts/{account_id}/owner`.\n`ADMIN` — everything an `OWNER` can do, except transferring ownership.\n`MEMBER` — no account administration. Access to each company is granted individually and reported as `access_level`; a member only sees the companies granted to them."

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

changedInput schema / $defs / GrantAssignment / properties / company_id / description

Previous value: -"Company (NIF) identifier within the account."New value: +"Unique identifier (UUID) of the company within the account."

addedInput schema / additionalProperties
```
Added value: +false
```

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?

Substantially exceeds the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true) by disclosing that the token is returned once and never readable again, that invitation_url is built from it, that send_email defaults to false so the caller must deliver the link, and exact 422 failure modes for null grants and OWNER roles. These are exactly the operational facts an agent needs and none are derivable from the annotation block.

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 verb and resource, then four tight bolded bullets keyed to the parameter names — easy to scan. A little of the content (the grants/null 422 rule, the send_email default) duplicates the schema descriptions nearly verbatim, so it is not maximally efficient, but nothing is padded.

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?

With no output schema, the description correctly carries the return contract (token, invitation_url) and explains the delivery model, which is the biggest risk of misuse here. Gaps remain around duplicate/resend behavior for an already-invited email and around the destructiveHint=true annotation, which is not elaborated on.

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

Parameters5/5

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

With 67% schema coverage, the description still adds real meaning: the distinction between omitting grants, sending [], and sending an explicit null (422) is spelled out, and it explains the delivery consequence of send_email rather than restating its default. It also explains why grants are meaningless for ADMIN/OWNER, which the enum schema only hints at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource — 'Creates a single-use invitation for a person to join the account' — with the 'single-use' qualifier and the role scoping making the operation unambiguous. It does not name the sibling invitation tools (beel_list_invitations, beel_get_invitation, beel_delete_invitation) to route an agent, so it stops short of full sibling differentiation.

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?

It gives concrete when/constraint guidance: grants apply only to MEMBER, OWNER cannot be invited at all, and ownership transfer is explicitly redirected to PUT /v1/accounts/{account_id}/owner — a genuine alternative route. It also tells the caller when send_email should be flipped to true. It never says when not to create an invitation (e.g. re-inviting an existing member), which keeps it below a 5.

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

Deploy Server