> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect AI assistants to your e-invoice.be account via MCP

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants interact with external services. Think of it as a USB-C port for AI — one protocol to connect any AI tool to e-invoice.be.

The e-invoice.be MCP server gives AI agents access to your invoices, credit notes, Peppol network data, and usage statistics — all through natural language.

<Note>
  All MCP tools are **read-only**. No data can be created, modified, or deleted through MCP. To create or send documents, use the [REST API](/api-reference).
</Note>

## Prerequisites

Before setting up MCP, you need:

1. An e-invoice.be account — [sign up at app.e-invoice.be](https://app.e-invoice.be)
2. An API key — go to **Settings → API Keys** in your dashboard ([learn more](/authentication))

**Server URL:** `https://api.e-invoice.be/mcp`

The endpoint is the same across all clients. Transport is streamable HTTP, authenticated with your API key as a Bearer token.

## Setup

<Tabs>
  <Tab title="Claude Code">
    ### Claude Code

    [Claude Code](https://docs.anthropic.com/en/docs/claude-code) supports remote MCP servers natively via streamable HTTP.

    **CLI (recommended):**

    ```bash theme={null}
    claude mcp add --transport http e-invoice https://api.e-invoice.be/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    This registers the server at user scope. To add it at project scope, append `--scope project`.

    **Manual JSON** — add to `~/.claude.json` (user scope) or `.claude/settings.local.json` (project scope):

    ```json theme={null}
    {
      "mcpServers": {
        "e-invoice": {
          "type": "http",
          "url": "https://api.e-invoice.be/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    After adding, restart Claude Code or run `/mcp` to verify the server appears in the list.

    <Card title="Claude Code MCP docs" icon="arrow-up-right-from-square" href="https://docs.anthropic.com/en/docs/claude-code/mcp">
      Official documentation for MCP in Claude Code
    </Card>
  </Tab>

  <Tab title="Claude Desktop">
    ### Claude Desktop

    Claude Desktop does not yet support remote streamable HTTP MCP servers directly. You need [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge (requires Node.js ≥ v18).

    **Step 1** — Open the config file from **Claude → Settings → Developer → Edit Config**:

    | OS      | Config path                                                       |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    **Step 2** — Add (or merge into) the `mcpServers` key:

    ```json theme={null}
    {
      "mcpServers": {
        "e-invoice": {
          "command": "npx",
          "args": [
            "mcp-remote@latest",
            "https://api.e-invoice.be/mcp",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```

    **Step 3** — Restart Claude Desktop. The e-invoice tools appear under the hammer (🔨) icon in the composer.

    <Card title="Claude Desktop MCP docs" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/docs/develop/connect-local-servers">
      Official documentation for connecting MCP servers to Claude Desktop
    </Card>
  </Tab>

  <Tab title="ChatGPT">
    ### ChatGPT

    ChatGPT supports remote MCP servers as custom connectors (available on Plus, Pro, Business, and Enterprise plans).

    <Warning>
      Custom connectors via developer mode are currently **not available** for all account types in the EEA, GB, and CH regions. Since most e-invoice.be users are in the EU, verify that your ChatGPT plan supports this feature before proceeding.
    </Warning>

    **Setup flow:**

    1. Open [chatgpt.com](https://chatgpt.com) → **Settings → Connectors → Advanced → Developer mode** (toggle on)
    2. Click **Create → Add custom connector**
    3. Fill in the connector details:
       * **Name:** `e-invoice`
       * **Description:** Send, validate, and look up Peppol invoices
       * **MCP server URL:** `https://api.e-invoice.be/mcp`
       * **Authentication:** Custom header
         * Header name: `Authorization`
         * Header value: `Bearer YOUR_API_KEY`
    4. Save and accept the trust prompt
    5. Enable the connector inside any chat via the **+ → Connectors** menu

    <CardGroup cols={2}>
      <Card title="ChatGPT connectors overview" icon="arrow-up-right-from-square" href="https://help.openai.com/en/articles/11487775-connectors-in-chatgpt">
        Learn about connectors in ChatGPT
      </Card>

      <Card title="Developer mode docs" icon="arrow-up-right-from-square" href="https://platform.openai.com/docs/guides/developer-mode">
        Enable custom MCP connectors
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Cursor">
    ### Cursor

    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

    ```json theme={null}
    {
      "mcpServers": {
        "e-invoice": {
          "url": "https://api.e-invoice.be/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    After saving, restart Cursor or open a new chat session. The tools will appear in the MCP tools list.

    <Card title="Cursor MCP docs" icon="arrow-up-right-from-square" href="https://docs.cursor.com/context/model-context-protocol">
      Official documentation for MCP in Cursor
    </Card>
  </Tab>

  <Tab title="VS Code">
    ### VS Code (GitHub Copilot)

    Add to `.vscode/mcp.json` in your project root:

    ```json theme={null}
    {
      "servers": {
        "e-invoice": {
          "type": "http",
          "url": "https://api.e-invoice.be/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Alternatively, add to your user or workspace `settings.json` under the `mcp.servers` key.

    <Card title="VS Code MCP docs" icon="arrow-up-right-from-square" href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers">
      Official documentation for MCP in VS Code
    </Card>
  </Tab>

  <Tab title="Windsurf">
    ### Windsurf

    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "e-invoice": {
          "type": "http",
          "url": "https://api.e-invoice.be/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Restart Windsurf after saving the configuration.
  </Tab>
</Tabs>

<Tip>
  Don't have an API key yet? See the [Authentication](/authentication) guide to create one.
</Tip>

## Available Tools

### Documents

| Tool                       | Description                                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `get_document`             | Retrieve a single invoice or credit note by ID, including line items, tax details, payment info, and attachments |
| `get_document_attachments` | List all attachments for a document                                                                              |
| `get_document_attachment`  | Get a specific attachment with a signed download URL (valid for 1 hour)                                          |
| `get_document_timeline`    | Get the chronological event history for a document (creation, validation, transmission, delivery)                |

### Inbox

| Tool                     | Description                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `get_inbox`              | List all received documents with filtering by type, sender, date range, and full-text search |
| `get_inbox_invoices`     | List only received invoices                                                                  |
| `get_inbox_credit_notes` | List only received credit notes                                                              |

### Outbox

| Tool         | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `get_outbox` | List all sent documents with filtering by receiver, date range, and full-text search |

### Drafts

| Tool         | Description                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------- |
| `get_drafts` | List draft documents with filtering by state (DRAFT, TRANSIT, FAILED), type, and date range |

### Peppol Lookup

These tools are **public** and do not require authentication.

| Tool                      | Description                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `get_lookup_peppol_id`    | Verify if a participant is registered on the Peppol network and retrieve their supported document types |
| `get_lookup_participants` | Search for Peppol participants by name, with optional country filter                                    |

### Statistics

| Tool        | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `get_stats` | Retrieve sending and receiving statistics, grouped by day, week, or month |

## Example Prompts

Once connected, you can interact with your e-invoice.be account using natural language:

* *"Show me all invoices received this month"*
* *"Get the details and timeline of document doc\_abc123"*
* *"Is the company with VAT number BE0848934496 registered on Peppol?"*
* *"Search for Peppol participants named 'OpenPeppol' in Belgium"*
* *"Show my sending and receiving stats for the last 3 months, aggregated by month"*
* *"List all failed documents in my drafts"*
* *"What attachments are on invoice doc\_xyz789?"*

## Troubleshooting

### Tools not appearing after setup

1. **Restart the application** — most MCP clients only load server configurations on startup.
2. **Verify your API key** — run a quick test with curl to confirm it works:
   ```bash theme={null}
   curl -s https://api.e-invoice.be/api/me/ \
     -H "Authorization: Bearer YOUR_API_KEY"
   ```
3. **Check the server URL** — make sure you're using `https://api.e-invoice.be/mcp` (no trailing slash).

### Claude Desktop: tools not showing

* Check the log file for errors:
  * **macOS:** `tail -n 50 ~/Library/Logs/Claude/mcp.log`
  * **Windows:** open `%APPDATA%\Claude\logs\mcp.log`
* Verify Node.js is installed and on your PATH: `node --version` (v18+ required).
* Test `mcp-remote` manually to surface auth errors:
  ```bash theme={null}
  npx mcp-remote@latest https://api.e-invoice.be/mcp \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```
* Ensure your JSON is valid — a trailing comma or missing quote will silently prevent loading.

### ChatGPT: connector not available

* Custom connectors require **Developer mode** to be enabled under Settings → Connectors → Advanced.
* Developer mode is not available on all plans or in all regions (EEA/GB/CH restrictions may apply).
* After adding the connector, you must explicitly enable it in each new chat via the **+ → Connectors** menu.

### Authentication errors

* API keys are prefixed with your tenant — make sure you copied the full key.
* Keys created for the [Admin API](/admin-api) (reseller keys) will not work with MCP.
* If you recently rotated your key, update the configuration file and restart the client.

## Security

<Warning>
  Your API key gives MCP access to all read-only data within your tenant. Treat it with the same care as any API credential.
</Warning>

* **Read-only access** — MCP tools cannot create, modify, or delete any data
* **Tenant-scoped** — your API key determines which tenant's data is accessible
* **Lookup tools are public** — `get_lookup_peppol_id` and `get_lookup_participants` work without authentication
* **Best practice** — consider creating a dedicated API key for MCP access, separate from your application's key

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/authentication">
    Get your API key and learn about authentication
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full REST API for creating and sending documents
  </Card>

  <Card title="Webhooks" icon="webhook" href="/essentials/webhooks">
    Receive real-time notifications for document events
  </Card>
</CardGroup>