Overview

The BeeL. MCP server lets an AI assistant operate the BeeL. API on your behalf through the Model Context Protocol: issue compliant invoices, manage NIFs, customers and products, connect payments, and read your fiscal data — all in natural language, from the client you already use.

It is hosted and remote, with no installation. Point your MCP client at the server URL, sign in with your BeeL. account, and the assistant gains access to the same API you use — scoped to exactly the permissions you approve.

https://mcp.beel.es/mcp

Connect your client

https://mcp.beel.es/mcp

Authentication

The hosted server supports two authentication methods:

• OAuth (recommended) — your MCP client opens a browser window and you sign in with your BeeL. account on the BeeL. consent screen, where you pick the account, the scopes, and the environment (Test vs Live). No keys to copy around, and you can revoke a client's access at any time.
• API key — pass a BeeL. API key as a bearer token in the Authorization header. Use this for clients without OAuth support and for autonomous agents.

Clients that support OAuth need only the server URL — the server advertises its authorization flow automatically and walks you through sign-in on first use. Under the hood it implements the MCP authorization spec (OAuth 2.1 with PKCE, discovery metadata, and dynamic client registration), so any MCP client can register itself.

What you can do

• Issue invoices end to end — pick standard (F1) vs simplified (F2), validate the NIF, set the regime keys, and clear the VeriFactu gates before issuing.
• Fix invoices the compliant way — void (anulación) vs corrective (rectificativa R1–R5).
• Onboard a NIF until it can issue Live — readiness, default series, VeriFactu, payments.
• Manage customers and products, in bulk when needed.
• Read your data — invoices, fiscal summaries, usage — and even preview an invoice PDF inline in the chat.

Built-in guardrails

The server is designed so an assistant cannot skip a fiscal step:

• VeriFactu-aware. Issuing tools surface the readiness blockers (ENV_MISMATCH, NIF_NOT_REGISTERED, NIF_REPRESENTATION_REQUIRED) instead of failing blindly.
• Idempotent writes. Invoice creation carries a stable idempotency key, so a retried request never duplicates a VeriFactu invoice.
• Least privilege. You approve a specific set of scopes on the consent screen; the assistant never gets more than you grant.

Building autonomous agents

If you're building agentic software, pass a BeeL. API key as a bearer token directly to the hosted server — it speaks Streamable HTTP, so any MCP SDK (or plain HTTP) works:

curl https://mcp.beel.es/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Don't embed API keys in code. Provide them through a secrets vault or environment variable, and use a dedicated test key (beel_sk_test_…) until you're ready to work with Live data.

Troubleshooting

• "Unauthorized" / empty scopes — the token was rejected or carried no scopes. For an API key, check it is active and copied without extra spaces at Settings → API Keys. For OAuth, remove and re-add the server so the client runs sign-in again and you approve the scopes.
• The client can't reach the server — remove the connector and add it again; some clients cache a failed authorization attempt. Confirm the URL is exactly https://mcp.beel.es/mcp.
• Changes not taking effect — after editing your client's MCP configuration, restart the client completely.

Next