# prtg-mcp

MCP server for **PRTG Network Monitor** (Paessler network/infrastructure
monitoring). Exposes PRTG's native HTTP API's sensors, devices, and
historic sensor data as MCP tools.

<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

Unlike most integrations in this program, PRTG has **no separate login or
token exchange**: the username and a "passhash" (generated in PRTG's UI
under *My Account -> API Key*, not the literal account password) are sent
as plain query parameters on every single call. There is therefore
nothing to cache — each call is already fully self-contained and
stateless by the vendor's own design.

### HEADER authentication parameters

| Header | Type | Required | Default | Allowed values | Description | Example |
|---|---|---|---|---|---|---|
| `X-PRTG-Server-Url` | string | Yes | None | None | PRTG core server hostname (without the protocol prefix) | `prtg.example.com` |
| `X-PRTG-Username` | string | Yes | None | None | PRTG API username | `api_user` |
| `X-PRTG-Passhash` | string | Yes | None | None | PRTG "passhash" (generated on the My Account -> API Key page in the PRTG UI; not the plaintext account password) | `1234567890` |

Missing any header returns `401`:
```json
{
  "error": "Missing credentials",
  "message": "This server requires the X-PRTG-Server-Url, X-PRTG-Username, and X-PRTG-Passhash headers",
  "required_headers": ["X-PRTG-Server-Url", "X-PRTG-Username", "X-PRTG-Passhash"],
  "optional_headers": []
}
```

An invalid credential surfaces as a tool-level error envelope (see
[Error envelope](#error-envelope) below), classified from PRTG's HTTP
status code — a 401/403 maps to `unauthorized`. On any non-2xx response
this server tries to extract a `message`/`error` field from the JSON body
and falls back to the raw response text if that body isn't JSON (PRTG can,
for certain malformed requests, fall back to an XML `<error>` body even on
the `.json` endpoint).

## 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 PRTG)

## Tool List

| Tool | Description | Parameters |
|---|---|---|
| `prtg_get_sensors` | List all sensors with their current status/values | `count` (optional, default 50, hard limit 200) |
| `prtg_get_devices` | List all monitored devices with their status and owning probe/group | `count` (optional, default 50, hard limit 200) |
| `prtg_get_sensor_historic_data` | Get a given sensor's historical monitoring data within a date range | `sensor_id`, `start_date`, `end_date` (all required), `avg` (optional, default 3600 seconds) |

All 3 tools are read-only (`readOnlyHint=True`, `idempotentHint=True`); there are no write/delete tools in this service.

`count` has no documented vendor-side hard maximum for PRTG's `table.json` endpoint, so this server applies the platform's own fallback ceiling instead of passing values through unchecked: default 50, values above 200 are silently clamped down to 200 rather than sent to PRTG as-is.

### Response format

Both endpoints this server calls (`table.json`, `historicdata.json`) are the vendor's JSON-suffixed variants, so on success the client only ever parses JSON. PRTG's HTTP API can in principle return XML for other endpoints/params, so the client parses defensively: a non-2xx response is classified into the structured error envelope below, and if a 2xx response ever fails to parse as JSON its raw text is returned under a `raw_response` key instead of raising.

### Error envelope

Tool errors are returned as a structured JSON string instead of a raised exception, so the calling agent can branch on `code` and decide whether to retry:

```json
{"error": {"code": "upstream_error", "message": "...", "retryable": true}}
```

`code` is one of: `not_configured`, `unauthorized`, `not_found`, `invalid_argument`, `rate_limited`, `upstream_error`. Empty result sets are returned as a normal (non-error) empty collection, not as `not_found`.

Tool return values (success and error alike) are compact JSON (`ensure_ascii=False`, no `indent`) capped at 20,000 characters — an oversized result truncates its largest list field and reports `truncated`/`original_count` rather than returning an unbounded blob.

## 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-PRTG-Server-Url: prtg.example.com" \
  -H "X-PRTG-Username: api_user" \
  -H "X-PRTG-Passhash: <your-passhash>" \
  -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": "prtg_get_sensors",
      "arguments": {}
    }
  }'
```

**Live-verified** (2026-07-30) against a real PRTG core server, all 3
tools called end-to-end through this running server with real
credentials: `prtg_get_sensors` and `prtg_get_devices` both returned `200`
with a real `prtg-version` string and a valid (empty) result set — this
particular test account has zero sensors/devices provisioned under its
visible scope, confirmed as a genuine "no data" condition (not an auth
failure) by separately querying `content=probes`, which returned real
data (the PRTG Root probe plus several real scheduling objects) using the
exact same credentials. `prtg_get_sensor_historic_data`, called with a
non-sensor object ID (since no real sensor ID was available), correctly
reached the API and returned the vendor's own content-level error ("The
selected object cannot be used here"), proving the request/auth pipeline
is wired correctly.

## API Reference

- Public, no login required:
  - Sensors/Devices table format: https://www.paessler.com/manuals/prtg/multiple_object_property_or_status#supported_output
  - Historic data: https://www.paessler.com/manuals/prtg/historic_data

## Known Gaps

- **Scope is exactly MSPbots' 3 configured endpoints, not the vendor's
  full API surface** — PRTG's API also covers live sensor control
  (pause/resume/acknowledge), object creation/deletion, notifications,
  reports, and more; those are out of scope here.
- **Sensor/device data could not be demonstrated with real records** — the
  provided test account (`Dash_Display`, likely a dashboard-only display
  account) has zero sensors and zero devices provisioned in its visible
  scope on this particular PRTG instance. Live testing confirmed this is
  a genuine empty result (not an auth or implementation bug) by
  successfully querying a different, always-populated object type
  (`content=probes`) with the same credentials and getting real data back.
- **`prtg_get_sensor_historic_data` could not be tested with a real
  sensor ID** for the same reason (no sensors exist to reference); it was
  instead verified by confirming the vendor's own content-level error
  response for an invalid object ID, which proves the request format and
  authentication are correct.