# Overview

Connect AI assistants to BeeL. through the Model Context Protocol — issue invoices, manage NIFs and customers, and read your fiscal data in natural language, with VeriFactu guardrails built in.

The **BeeL. MCP server** lets an AI assistant operate the BeeL. API on your behalf through the [Model Context Protocol](https://modelcontextprotocol.io): issue 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.

```text
https://mcp.beel.es/mcp
```

## Connect your client

**Claude** — In Claude (web/desktop): Settings → Connectors → Add custom connector, and enter the server URL. Claude opens the BeeL consent screen to sign in.

```text
https://mcp.beel.es/mcp
```

**Claude Code** — Run this in your terminal:

```bash
claude mcp add --transport http beel https://mcp.beel.es/mcp
```

**Cursor** — Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Cursor prompts you to sign in with BeeL:

```json
{
  "mcpServers": {
    "beel": {
      "url": "https://mcp.beel.es/mcp"
    }
  }
}
```

**ChatGPT** — In ChatGPT: Settings → Connectors → Advanced → Add custom connector, and enter the server URL (requires a plan with connectors enabled).

```text
https://mcp.beel.es/mcp
```

**Codex** — Run this in your terminal:

```bash
codex mcp add beel --url https://mcp.beel.es/mcp
```

**VS Code (Copilot)** — Add this to your VS Code settings.json:

```json
{
  "mcp": {
    "servers": {
      "beel": {
        "type": "http",
        "url": "https://mcp.beel.es/mcp"
      }
    }
  }
}
```

**Antigravity** — Add this to your ~/.gemini/settings.json (Antigravity / Gemini):

```json
{
  "mcpServers": {
    "beel": {
      "httpUrl": "https://mcp.beel.es/mcp"
    }
  }
}
```

**Devin** — Add this to your Devin MCP configuration:

```json
{
  "mcpServers": {
    "beel": {
      "transport": "HTTP",
      "url": "https://mcp.beel.es/mcp"
    }
  }
}
```

<Callout type="info">
  Any MCP client that speaks **Streamable HTTP** works, even if it is not listed above — point it at `https://mcp.beel.es/mcp` and authenticate with OAuth or an API-key bearer token.
</Callout>

## 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](https://app.beel.es/ajustes/api-keys) 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.

<Callout type="warn">
  **Connecting means working with your Live data** unless you explicitly pick the sandbox (Test) environment on the consent screen. The scopes you approve are the ceiling — the assistant never gets more than you grant.
</Callout>

## 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** through BeeL. — void vs corrective invoice (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:

```bash
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](https://app.beel.es/ajustes/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.

## Related

<Related>

- [Tools & prompts](/mcp/tools)

</Related>

---

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