# oitvoip-mcp

MCP server for **Oitvoip** (hosted VoIP/UCaaS reseller platform, built on
**NetSapiens** — API host pattern is `{tenant-pbx-host}/ns-api/`). Exposes
the NetSapiens ns-api's domain, reseller, device, subscriber, and CDR
methods as MCP tools.

> Naming note: MSPbots' own integration is registered as "Oitvoip"
> (`subjectCode=NS` — short for NetSapiens); the underlying API and all
> official documentation reference "NetSapiens" / "ns-api". This MCP
> covers exactly the 5 methods MSPbots itself has configured.

<div align="center">

## MSPbots Connector

**The MCP Gateway built for MSPs: visible, controlled, and your data stays where it belongs.**

[**Get started at connect.mspbots.ai →**](https://connect.mspbots.ai)

</div>

---

MSPbots Connector gives your AI clients one MCP URL to reach your entire MSP stack (RMM, PSA, documentation, security, finance), and gives you control over who can call which tool and a record of everything that was called.

**Hosted service: [connect.mspbots.ai](https://connect.mspbots.ai)** · Free to use.

### Why Connector

![MSPbots Connector](https://stgoss.mspbots.ai/files/mcp/mspbots-mcp.png)

| | |
|---|---|
| **Visible** | Every tool call is logged: who, which vendor, when. Usage dashboard, CSV export, SIEM streaming. |
| **Controlled** | Role-based, per-tool allowlist. Deny by default. |
| **Protected** | Credentials encrypted per record. AI clients never see your vendor passwords or tokens. |
| **MSP-native** | Built for the MSP stack only: RMM, PSA, documentation, security, finance. |

### Quick start

1. **Sign up** at [connect.mspbots.ai](https://connect.mspbots.ai).
2. **Connect your vendors.** Pick from 150+ connectors and authorize each one on the vendor's own page, or bring your own API keys. No extra vendor accounts needed.
3. **Set access.** Create roles and decide which tools each role may call. Nothing is allowed until you allow it.
4. **Add your MCP URL to your AI client.** Copy the URL from your Connector dashboard into Claude, ChatGPT, Cursor, VS Code, Gemini, Codex, or any MCP-capable client.
5. **Ask your AI to do real work**, and watch every call appear in the audit log.

### Features

**Unified gateway**
- One MCP URL for all your AI clients
- 150+ connectors across the MSP stack
- Custom MCP servers supported, free
- Authorization happens on each vendor's own page; the AI never sees passwords or tokens
- Bring your own credentials: use the vendor API keys you already have
- Multiple accounts per app; connect once, reuse across AI clients
- Tool search: finds the right action for the task
- One sign-in; vendor credentials are injected behind the scenes and OAuth tokens refresh automatically

**Visibility**
- Audit log for every tool call (who, which vendor, when)
- Usage dashboard: call volume, top vendors, error rate, per-user activity
- Export audit logs to CSV, or stream to Loki, Graylog, or LogScale (SIEM)
- Optional recording of tool arguments and result summaries (off by default, enabled per organization)

**Control**
- Per-role, per-tool allowlist, deny by default
- owner / admin / member roles
- SCIM provisioning with Entra ID, Okta, JumpCloud, and Google Workspace

**Security**
- Credentials encrypted one record at a time (AES-256-GCM, per-record key)
- AI clients authenticate with OAuth 2.1 + PKCE
- Vendor responses are scanned for prompt-injection patterns and returned as structured data. This is one layer of defense, not a guarantee against every attack.
- Static egress IP for customer firewall and API allowlisting

### Pricing

**Free.**

Links: [connect.mspbots.ai](https://connect.mspbots.ai) · [mspbots.ai](https://mspbots.ai)

---

## Overview

- Stateless HTTP service. No credentials are ever persisted — each request
  supplies its own credentials via headers, used only for the lifetime of
  that single request.
- Supports concurrent requests; per-request credential isolation is done via
  Python `contextvars`, not a global/shared client instance.
- Entry points: `POST /mcp` (MCP protocol) and `GET /health` (health check).
- Default port: `8080` (configurable via `MCP_HTTP_PORT`).

## Authentication

NetSapiens uses a standard OAuth2 **password grant**:

```
POST https://{site}/ns-api/oauth2/token/
  grant_type=password&client_id=...&client_secret=...&username=...&password=...
-> {"access_token": "...", "expires_in": 3600, "token_type": "Bearer", ...}
```

The resulting `access_token` is valid for 1 hour, but this server
re-authenticates fresh on every single tool call rather than caching it
across MCP requests — nothing is cached or persisted. Every real ns-api
call then sends `Authorization: Bearer <access_token>`.

### HEADER Authorization Parameters

| Header | Type | Required | Default | Allowed values | Description | Example |
|---|---|---|---|---|---|---|
| `X-Oitvoip-Site` | string | Yes | None | None | Tenant PBX hostname (without protocol prefix) | `pbx.example.com` |
| `X-Oitvoip-Client-Id` | string | Yes | None | None | NetSapiens OAuth2 API Client ID | `58900.mspbot` |
| `X-Oitvoip-Client-Secret` | string | Yes | None | None | NetSapiens OAuth2 API Client Secret | `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6` |
| `X-Oitvoip-Username` | string | Yes | None | None | Subscriber login name (including the domain suffix) | `1000@example` |
| `X-Oitvoip-Password` | string | Yes | None | None | Corresponding password | `••••••••` |

Missing any header returns `401`:
```json
{
  "error": "Missing credentials",
  "message": "This server requires the X-Oitvoip-Site, X-Oitvoip-Client-Id, X-Oitvoip-Client-Secret, X-Oitvoip-Username, X-Oitvoip-Password headers",
  "required_headers": ["X-Oitvoip-Site", "X-Oitvoip-Client-Id", "X-Oitvoip-Client-Secret", "X-Oitvoip-Username", "X-Oitvoip-Password"],
  "optional_headers": []
}
```

An invalid credential or an authenticated-but-under-scoped subscriber
account surfaces as a tool-level `unauthorized` error envelope (message
includes the vendor's own detail, e.g. `Invalid Scope [APP001]`), not an
HTTP-level error from this server — see Known Gaps.

## Environment Variables

| Variable | Type | Required | Default | Description |
|---|---|---|---|---|
| `MCP_HTTP_PORT` | int | No | `8080` | HTTP listen port |
| `MCP_HTTP_HOST` | string | No | `0.0.0.0` | HTTP listen address |

## MCP Endpoint

- `POST /mcp` — MCP protocol (streamable HTTP transport)
- `GET /health` — health check, returns `{"status": "ok"}` (pure local probe, does not call the vendor API)

## Tool List

| Tool | Description | Parameters |
|---|---|---|
| `oitvoip_get_domains` | List all provisioned domains (tenants) under the reseller account | None |
| `oitvoip_get_resellers` | Get reseller-level details for a given domain | `domain` (required) |
| `oitvoip_get_devices` | List the registered SIP devices/endpoints under a given domain | `domain` (required) |
| `oitvoip_get_subscribers` | List the users/extensions under a given domain | `domain` (required) |
| `oitvoip_get_cdr2` | Get call detail records (CDR) for a given domain and date range | `domain`, `start_date`, `end_date` (all required) |

Responses are the vendor's JSON (array or object depending on the method),
serialized compactly (no indentation, `ensure_ascii=False`). If a response
would exceed ~20,000 characters, the largest list field is truncated and
the result includes `truncated: true` plus the original count, rather than
returning an unbounded blob. All 5 tools are read-only (`readOnlyHint`) —
there are no write/delete tools in this service.

On error, tools return a structured JSON error envelope instead of raising:

```json
{"error": {"code": "unauthorized", "message": "...", "retryable": false}}
```

`code` is one of `not_configured` / `unauthorized` / `not_found` /
`invalid_argument` / `rate_limited` / `upstream_error`; `retryable`
indicates whether the Agent may safely retry (true for `rate_limited` and
`upstream_error`).

## Test Example

```bash
# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Oitvoip-Site: pbx.example.com" \
  -H "X-Oitvoip-Client-Id: 58900.mspbot" \
  -H "X-Oitvoip-Client-Secret: <your-client-secret>" \
  -H "X-Oitvoip-Username: 1000@example" \
  -H "X-Oitvoip-Password: <your-password>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "oitvoip_get_subscribers",
      "arguments": {"domain": "example.58900.service"}
    }
  }'
```

**Live-verified** (2026-07-30) against a real tenant, all 5 tools called
end-to-end through this running server: `oitvoip_get_subscribers` returned
real subscriber/extension records; `oitvoip_get_devices` returned real
registered SIP devices (Polycom endpoints, live registration state);
`oitvoip_get_cdr2` returned real call detail records for the given date
range. `oitvoip_get_domains` and `oitvoip_get_resellers` correctly reached
the API and surfaced a clean, expected `401 Invalid Scope [APP001]`
tool-level error — the provided test credentials are a subscriber-level
account (`scope: "Office Manager"`), which does not carry domain/reseller
admin privileges on this particular NetSapiens deployment; see Known Gaps.

## API Reference

- Public, no login required: https://api.ucaasnetwork.com/ns-api/apidoc/
  (full ns-api reference, including OAuth2, Domain, Reseller, Device,
  Subscriber, and CDR objects)

## Known Gaps

- **Scope is exactly MSPbots' 5 configured endpoints, not the vendor's
  full API surface** — ns-api also covers Callqueue, Agent, Phonenumber,
  Dialplan, Contacts, Presence, Call Queue Report/Stat, real-time Call
  control, and more (per the public docs' own object list); those are out
  of scope here.
- **`oitvoip_get_domains` and `oitvoip_get_resellers` could not be fully
  live-verified with real data** — the provided test account authenticates
  successfully (proving the OAuth2 flow and this implementation are
  correct) but is scoped as a subscriber-level "Office Manager" role,
  which NetSapiens rejects for these two admin-level objects with `401
  Invalid Scope [APP001]`. This is a credential-privilege limitation of
  the specific test account, not a bug in this server — `oitvoip_get_
  subscribers`, `oitvoip_get_devices`, and `oitvoip_get_cdr2` all
  succeeded with real data using the exact same access token from the
  exact same login.
- **CDR date range fields (`start_date`/`end_date`) are unvalidated
  strings** — passed through to the vendor as-is in `YYYY-MM-DD HH:MM:SS`
  format, matching MSPbots' own stored usage; no client-side date parsing
  is performed.