> ## 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 an AI assistant to your e-invoice.be company with the Model Context Protocol (MCP) and read your documents, Peppol data and usage statistics.

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants use external services. The e-invoice.be MCP server gives AI agents access to your invoices, credit notes, Peppol network data and usage statistics.

<Note>
  All MCP tools are read-only. An MCP client cannot create, change or delete data. To create or send documents, use the [API reference](/api-reference). To create or send documents from a terminal, or from an AI agent that can run shell commands, use the [peppol CLI](/cli).
</Note>

## Prerequisites

Before you set up MCP, you need:

1. An e-invoice.be account. Sign up at [app.e-invoice.be](https://app.e-invoice.be).
2. The API key of your company. Open **API Settings** in the app and copy the key. See [Authentication](/authentication).

The server URL is `https://api.e-invoice.be/mcp`. It is the same for all clients. The transport is streamable HTTP, and you authenticate with your API key as a Bearer token.

## Setup

<Tabs>
  <Tab title="Claude Code">
    [Claude Code](https://docs.anthropic.com/en/docs/claude-code) supports remote MCP servers with streamable HTTP.

    Use the command line (recommended):

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

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

    As an alternative, add this JSON 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"
          }
        }
      }
    }
    ```

    Then restart Claude Code or run `/mcp` and make sure that the server is 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 does not connect directly to remote streamable HTTP MCP servers. Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge. It needs Node.js 18 or later.

    <Steps>
      <Step title="Open the configuration file">
        Select **Claude → Settings → Developer → Edit Config**. The file location is:

        | OS | Configuration file |
        | - | - |
        | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
        | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
        | Linux | `~/.config/Claude/claude_desktop_config.json` |
      </Step>

      <Step title="Add the server">
        Add the `mcpServers` key, or merge the entry into the key that is there:

        ```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>

      <Step title="Restart Claude Desktop">
        The e-invoice tools then show in the tools menu of the composer.
      </Step>
    </Steps>

    <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 supports remote MCP servers as custom connectors on the Plus, Pro, Business and Enterprise plans.

    <Warning>
      Custom connectors in developer mode are not available for all account types in the EEA, the United Kingdom and Switzerland. Make sure that your ChatGPT plan supports this feature before you continue.
    </Warning>

    <Steps>
      <Step title="Enable developer mode">
        Open [chatgpt.com](https://chatgpt.com) and go to **Settings → Connectors → Advanced**. Set **Developer mode** to on.
      </Step>

      <Step title="Create the connector">
        Select **Create → Add custom connector** and enter these values:

        * **Name:** `e-invoice`
        * **Description:** Read and look up Peppol invoices
        * **MCP server URL:** `https://api.e-invoice.be/mcp`
        * **Authentication:** Custom header, with header name `Authorization` and header value `Bearer YOUR_API_KEY`
      </Step>

      <Step title="Save">
        Save the connector and accept the trust prompt.
      </Step>

      <Step title="Enable the connector in a chat">
        In each chat, select **+ → Connectors** and enable the connector.
      </Step>
    </Steps>

    <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">
    Add this JSON to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (one project):

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

    Save the file, then restart Cursor or open a new chat session. The tools show 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">
    For GitHub Copilot in VS Code, add this JSON to `.vscode/mcp.json` in the root of your project:

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

    As an alternative, add the server to your user or workspace `settings.json` below 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">
    Add this JSON 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"
          }
        }
      }
    }
    ```

    Save the file, then restart Windsurf.
  </Tab>
</Tabs>

<Tip>
  If you have no API key, see [Authentication](/authentication).
</Tip>

## Available tools

### Documents

| Tool | Description |
| - | - |
| `get_document` | Get one invoice or credit note by ID, with line items, tax details, payment data and attachments |
| `get_document_attachments` | List all attachments of a document (see [Attachments and PDF](/guides/attachments)) |
| `get_document_attachment` | Get one attachment with a signed download URL (valid for 1 hour) |
| `get_document_timeline` | Get the event history of a document in time sequence (creation, validation, transmission, delivery). See [Document lifecycle and delivery tracking](/guides/document-lifecycle) |

### Inbox

| Tool | Description |
| - | - |
| `get_inbox` | List all received documents; filter by type, sender, date range and search text |
| `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; filter by receiver, date range and search text |

### Drafts

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

### Peppol lookup

These tools are public and need no authentication.

| Tool | Description |
| - | - |
| `get_lookup_peppol_id` | Check if a participant is registered on the Peppol network and get the document types that it supports |
| `get_lookup_participants` | Search for Peppol participants by name, with an optional country filter |

### Statistics

| Tool | Description |
| - | - |
| `get_stats` | Get send and receive statistics by day, week or month. See [Usage statistics and credits](/guides/usage-statistics) |

## Example prompts

When the client is connected, you can ask questions about your company in natural language:

* *"Show me all invoices received this month"*
* *"Get the details and timeline of document doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"*
* *"Is the company with VAT number BE0848934496 registered on Peppol?"*
* *"Search for Peppol participants named 'OpenPeppol' in Belgium"*
* *"Show my send and receive statistics for the last 3 months, by month"*
* *"List all failed documents in my drafts"*
* *"What attachments are on invoice doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d?"*

## Troubleshooting

<AccordionGroup>
  <Accordion title="The tools do not show after setup">
    1. Restart the application. Most MCP clients load the server configuration only when they start.
    2. Make sure that your API key is correct. This request must return your company data:

       ```bash theme={null}
       curl -s https://api.e-invoice.be/api/me/ \
         -H "Authorization: Bearer $E_INVOICE_API_KEY"
       ```
    3. Make sure that the server URL is `https://api.e-invoice.be/mcp`, with no slash at the end.
  </Accordion>

  <Accordion title="Claude Desktop does not show the tools">
    * Look for errors in the log file:
      * macOS: `tail -n 50 ~/Library/Logs/Claude/mcp.log`
      * Windows: open `%APPDATA%\Claude\logs\mcp.log`
    * Make sure that Node.js 18 or later is installed and on your `PATH`: `node --version`.
    * Run `mcp-remote` manually to see authentication errors:

      ```bash theme={null}
      npx mcp-remote@latest https://api.e-invoice.be/mcp \
        --header "Authorization: Bearer $E_INVOICE_API_KEY"
      ```
    * Make sure that the JSON is valid. If the file has a comma at the end of a list or a missing quotation mark, Claude Desktop does not load the server and shows no error.
  </Accordion>

  <Accordion title="ChatGPT does not offer the connector">
    * Custom connectors need **Developer mode**. Enable it in **Settings → Connectors → Advanced**.
    * Developer mode is not available on all plans and in all regions. Limits can apply in the EEA, the United Kingdom and Switzerland.
    * Enable the connector in each new chat with the **+ → Connectors** menu.
  </Accordion>

  <Accordion title="Authentication errors">
    * Make sure that you copied the full API key.
    * An organisation API key for the [Admin API](/admin-api) does not work with MCP. Use the API key of a company.
    * If you reset your key, update the configuration file and restart the client.
    * For the HTTP status codes of the API, see [Errors and troubleshooting](/guides/errors).
  </Accordion>
</AccordionGroup>

## Security

<Warning>
  Your API key gives an MCP client access to all data of your tenant that the read-only tools can return. Protect it as you protect all API credentials.
</Warning>

* **Read-only access:** MCP tools cannot create, change or delete data.
* **Tenant scope:** the API key controls which tenant the tools can read. A tenant is one company.
* **Public lookup tools:** `get_lookup_peppol_id` and `get_lookup_participants` operate without authentication.
* **Sandbox company first:** use the API key of a sandbox company while you try MCP. See [Test mode and sandbox companies](/environments).

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Get your API key and learn how the API authenticates requests
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Create and send documents with the REST API
  </Card>

  <Card title="peppol CLI" icon="terminal" href="/cli">
    Create, validate and send documents from a terminal or a script
  </Card>

  <Card title="Webhooks" icon="webhook" href="/essentials/webhooks">
    Receive a notification for each document event
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.