Developers

ISPbox MCP Server

Every ISPbox workspace exposes a remote Model Context Protocol server. Connect Claude, ChatGPT, Cursor, Claude Code or any MCP-capable client and let AI work your panel: look up customers, answer "why is this client offline?", manage tickets, record payments and pull billing summaries - always limited to the permissions you grant, with every tool call audited.

Endpoint

https://<workspace>.ispbox.net/mcp

Transport: Streamable HTTP (POST, with SSE streaming). The endpoint requires authentication.

Authentication

1. Sign in with your ISPbox account (OAuth 2.1)

For people. Add the endpoint to your AI client and it opens a browser window to sign in and approve access. Only permissions your staff account already has can be granted, and you can revoke a connection anytime under My Account > AI Assistant. Discovery, dynamic client registration and PKCE are supported, so clients like Claude and ChatGPT connect with just the URL.

2. Workspace API key

For automations. Create a key under Settings > API and send it as Authorization: Bearer ispbx_.... The key's scopes decide which tools are visible.

claude mcp add ispbox --transport http https://<workspace>.ispbox.net/mcp \
  --header "Authorization: Bearer ispbx_..."

Tools

Tools are task-shaped and scope-gated: a connection only sees the tools its scopes allow.

Tool	Scope	What it does
`search-clients`	`clients.read`	Find clients by name, email, phone or account number.
`get-client`	`clients.read`	Full client overview: profile, services, balance, recent invoices, open tickets.
`create-client / update-client / add-client-note`	`clients.write`	Create and update clients, add internal notes.
`list-services / get-service`	`services.read`	Services with package, billing dates and connection details.
`diagnose-service`	`services.read`	"Why is this customer offline?" - service status + billing suspension + RADIUS session + router health with a verdict.
`create-service / update-service`	`services.write`	Subscribe a client to a package, change status or billing dates.
`get-service-usage / list-sessions / get-network-status`	`network.read`	Data usage, live sessions, router health and open incidents.
`list-packages`	`packages.read`	Plans with pricing, speeds and billing intervals.
`list-invoices / get-invoice / list-payments / get-client-balance / get-billing-summary`	`billing.read`	Receivables, payments, balances and monthly billing snapshots.
`record-payment / create-invoice`	`billing.write`	Record manual payments, create one-off invoices.
`void-invoice / reverse-payment`	`billing.write`	Destructive accounting actions - MCP clients ask for confirmation.
`list-tickets / get-ticket`	`tickets.read`	Ticket queues and full comment threads.
`create-ticket / reply-to-ticket / update-ticket`	`tickets.write`	Open tickets, reply (internal or customer-visible), change status.
`list-leads / create-lead / convert-lead`	`leads.*`	Sales pipeline: list, create and convert leads to clients.
`preview-message-audience`	`clients.read`	Count and sample the clients behind a router, network device, incident, location or status filter.
`send-client-message`	`messaging.send`	Email/SMS a targeted client group (two-phase: preview first, then explicit confirm). Router / downstream-device / incident / location targeting.
`list-monitored-devices`	`network.read`	Live device inventory with up/down status from connected LibreNMS/Zabbix, linked to network-map features.
`list-monitoring-alerts`	`network.read`	Active alerts/problems live from LibreNMS/Zabbix: severity, device, since when, acknowledged flag.
`ack-monitoring-alert`	`monitoring.manage`	Acknowledge NMS alerts with a required note (MCP clients ask for confirmation).
`get-network-health / get-network-changes`	`network.read`	The annotated network-monitoring graph (devices with loss and latency against baseline, links with verdict, root flag and utilisation, CPEs aggregated) and the change feed an agent polls between calls.
`get-target-health / get-link-health / list-targets`	`network.read`	One pinged host against its baseline with its patterns and path, one link with loss, added latency, utilisation vs capacity and what sits behind it, and the searchable target list.
`explain-degradation / compare-targets`	`network.read`	Root links with the degraded and clean targets that prove them plus a deterministic summary, and up to ten targets side by side with their shared path prefix.
`list-monitoring-events / list-probers`	`network.read`	Monitoring alert presets that opened or closed over a window, and the probe agents with their health, archive and disk state.
`list-diagnoses / get-diagnosis`	`network.read`	The deterministic hypotheses the module already formed (link fault, saturation, radio degradation, outage, customer side, plan saturation, upstream ISP, forecasts) with evidence, confidence and recommended actions.
`get-device-log-summary / list-device-log-events / list-log-templates`	`network.read`	What the devices themselves said: per-source volumes and silent senders, typed events for one host, link or source, and the message clusters no rule recognised yet.
`fetch-device-log / get-device-log-fetch`	`monitoring.manage`	Ask a prober for a window of real log lines out of its own archive and read it back. Privileged and audited: raw lines carry customer identifiers, so a token that names a user also needs that user to hold the settings permission, every read writes an audit entry, and a workspace credential only reads back windows a workspace credential asked for.
`ping-now / set-target-policy / set-diagnosis-feedback`	`network.write`	Queue an out-of-cycle ping, move a target to another alert policy, and record a human confirming or refuting a diagnosis.
`get-report`	`reports.read`	Run any panel report: AR aging, billing trend, revenue by location, package mix, client growth, top data users, tax summary, tickets summary.
`send-portal-invite / block-client / unblock-client`	`clients.write`	Support actions: portal invitation email, reasoned block (deprovisions services) and unblock with optional delinquency grace.
`pause-service-seasonally / resume-service-seasonally`	`services.write`	Seasonal holds: schedule or apply a billing-pausing suspension, resume and re-provision.
`list-visits / schedule-visit`	`tickets.*`	The technician calendar: list scheduled visits, book a visit on a ticket.
`search-inventory / find-inventory-unit`	`inventory.read`	Stock levels per item and per-serial unit lookup (who has it, where it is installed).
`list-credit-notes / list-ip-pools / list-campaigns`	`billing.read / network.read / marketing.read`	Credit notes, IPAM pool utilization and marketing campaigns.
`search-wiki`	`any`	Search the official ISPBox documentation and cite the article.
`list-staff-users / list-locations`	`clients.read`	Discover staff user ids (assignees, technicians) and location ids for the other tools.
`open-incident / update-incident / resolve-incident`	`network.write`	Full incident lifecycle: open on a map device (topology-resolved impact), a router, a location or the whole network (scope_type + scope_id), with started-at, ETA and notify-now; post public updates; resolve. Live on the status page at once.
`add-pending-charge`	`billing.write`	Put a one-time charge on the client's next invoice.
`update-lead / add-lead-activity`	`leads.write`	CRM: change pipeline state and log calls/emails/meetings with follow-up dates.

The server also ships prompts (daily-briefing, diagnose-client-connectivity, collections-review) and an ispbox-guide resource that teaches the AI the recommended flows.

Security model

OAuth connections are bound to a staff user; granted scopes are re-checked against the user's current panel permissions on every request.
Tools a connection cannot use are not just blocked - they are never listed.
Destructive tools (void invoice, reverse payment) are annotated so MCP clients require explicit confirmation.
Customer-authored text (ticket bodies, notes) is delimited as untrusted content to resist prompt injection.
Every tool call is logged with actor, arguments, result and duration - visible to workspace admins, next to a workspace-wide kill switch.