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

# AI assistant access (MCP)

> Connect Claude or another MCP client to your ISP data with an API key, and understand what it can read and what it can never do on its own.

# Connect an AI assistant to your ISP

**Centipid ISP Billing** is the Model Context Protocol (MCP) server for your workspace. It lets an external AI client — Claude, or any client that supports an HTTP MCP server — read your ISP data and answer questions in plain language. It reaches the same information the built-in AI Assistant reaches, through the same tools.

This is separate from the in-app assistant. The in-app assistant needs no setup; this page is for connecting a client that runs outside the billing application.

## Who can do this

Any operator user whose role grants **AI Chat** access. The key you create acts as you: it reaches exactly what your account reaches in the application, and no more. A member of staff without AI Chat access cannot create a working key.

## Prerequisites

* An operator account with AI Chat access.
* A client that supports an HTTP MCP server with custom request headers.
* Somewhere safe to store the key, such as a password manager or secret store.

## The endpoint

|                |                                       |
| -------------- | ------------------------------------- |
| Server name    | Centipid ISP Billing                  |
| URL            | `https://mcp.centipidbilling.com/mcp` |
| Method         | `POST`                                |
| Authentication | `Authorization: Bearer YOUR_KEY`      |

The URL is the same for every ISP. **Your key is what identifies your workspace** — it decides whose data the endpoint returns. Nothing in the address distinguishes one ISP from another.

<Note>
  The endpoint also answers on your own workspace URL, at `/mcp`. Either address works; the shared address above is easier to remember and is the one to use unless you have a reason to prefer your own domain.
</Note>

## Connect a client

<Steps>
  <Step title="Create a key">
    Open **Settings → Developer** and create a key. The key name is required. Name it after the device or client that will use it, such as `claude-desktop` or `office-laptop`, so you can revoke the right one later.

    The plaintext key is shown once, immediately after creation. Copy it then. It is not shown again, and a lost key cannot be recovered — revoke it and create another.
  </Step>

  <Step title="Add the endpoint to the client">
    In Claude Code, one command registers it:

    ```bash theme={null}
    claude mcp add --transport http centipid \
      https://mcp.centipidbilling.com/mcp \
      --header "Authorization: Bearer YOUR_KEY"
    ```

    Any client that accepts an HTTP MCP server with custom headers takes the same two values:

    ```json theme={null}
    {
      "mcpServers": {
        "centipid": {
          "type": "http",
          "url": "https://mcp.centipidbilling.com/mcp",
          "headers": { "Authorization": "Bearer YOUR_KEY" }
        }
      }
    }
    ```
  </Step>

  <Step title="Confirm it works">
    Your client should now list the server as **Centipid ISP Billing** with 23 tools available. `centipid` in the commands above is only the local shorthand you type; the name the client displays comes from the server itself.

    Ask the assistant something only your ISP would know, such as how much was collected today, or who expires in the next 24 hours. Real figures in the answer confirm the connection.

    To check from a terminal instead, list the available tools. A working key returns 23 of them:

    ```bash theme={null}
    curl -sS https://mcp.centipidbilling.com/mcp \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    ```
  </Step>
</Steps>

## What the assistant can do

Twenty-three tools. Twenty read only. Three can change something, and never do so on their own — see [Actions require your approval](#actions-require-your-approval).

| Area                | Tools                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Money               | `revenue_summary`, `payments_report`, `outstanding_invoices`, `amount_due`, `voucher_stock`                                                |
| Subscribers         | `subscriber_lookup`, `subscriber_status`, `list_subscribers`, `expiring_subscribers`, `top_data_users`                                     |
| Network and routers | `active_sessions`, `nas_status`, `router_resources`, `mikrotik_config`, `mikrotik_logs`, `mikrotik_read_command`, `run_mikrotik_diagnosis` |
| Plans and support   | `packages`, `open_tickets`, `search_documentation`                                                                                         |
| Requires approval   | `reconnect_subscriber`, `disconnect_no_expiry`, `apply_mikrotik_fix`                                                                       |

Router tools read live configuration and logs over the RouterOS API. `mikrotik_read_command` accepts read-only commands only; writes are refused.

## Actions require your approval

The three tools in the last row above do not perform their action when an assistant calls them. They record a request and return a pending status.

<Warning>
  Nothing on your network changes at the moment an assistant asks. The request appears in the application's AI Chat panel, in a conversation named **MCP session**, and waits for an administrator to confirm it. No subscriber is disconnected and no router configuration is altered until someone confirms it there.

  If an assistant reports one of these actions as completed, that report is wrong. Check the panel.
</Warning>

Confirming is subject to the same permission the equivalent screen requires. An account that cannot disconnect a subscriber in the application cannot confirm a disconnection here either.

## What a key can reach

* **Only your ISP.** Every figure comes from your own workspace. A key cannot read another operator's subscribers, payments, or routers, and no other operator's key can read yours.
* **Only your own permissions.** The key acts as the account that created it and is limited to that account's role.
* **Everything that account can see.** Anyone holding the key holds that access. Treat it as a password.

<Warning>
  Do not paste a key into messages, tickets, screenshots, or webhook payloads. If a key is exposed, revoke it in **Settings → Developer** immediately and create a replacement. Revoking takes effect at once and breaks only the client using that key.
</Warning>

Create one key per client rather than sharing one key across devices, so a single revocation does not disconnect everything.

## Common failures

### The response says the API key is unknown

The key is wrong, has been revoked, or was truncated when copied. A key has the form `12|…`; the digits before the vertical bar are part of it. Copy the whole value. If in doubt, revoke it and create another.

### The response is 403 Forbidden

The key is valid, but the account that created it does not have AI Chat access. An administrator can grant it on that user's role, after which the existing key works.

### Only 15 tools are listed

The client read one page of results and stopped. Restart the client. If the count stays at 15, the client is not reading the tool list to the end; check for an update.

### The assistant returns another ISP's data

Stop and revoke the key. Create a replacement from the workspace you intend to use, and report the incident to Centipid support. This should not be possible.

### An approved-tool request appears to do nothing

Expected. Open the AI Chat panel in the application and confirm the request there. Until then, nothing has happened.

## Related pages

* [Settings](/getting-started/settings) — where keys are created and revoked, under Developer.
* [Staff and permissions](/subscribers/staff-and-permissions) — granting AI Chat access to a role.
* [Support](/reference/support) — reporting a suspected access problem.