cloudradial-mcp

CloudRadial MCP server — exposes the CloudRadial REST API (client portal / PSA-adjacent MSP platform) as MCP tools.

Naming note: app.mspbots.ai calls this integration "CloudRadial" (sys_integration.subject_code = CLOUDRADIAL). The vendor's public API is documented at developers.cloudradial.com and its Swagger UI at https://api.us.cloudradial.com/swagger.

Overview

This server implements the Model Context Protocol (Streamable HTTP/SSE transport) and wraps every operation in CloudRadial's official OpenAPI 3.0 spec (v1, 34 operations across 8 resource groups: Company, Article, Feedback, Token, Archive/ArchiveItem, FlexibleAsset, FlexibleAssetType, and the OData v2 metadata endpoint). It follows the MSPbots Vendor MCP Service SOP: stateless, no stored credentials, per-request header authentication.

The underlying API authenticates via HTTP Basic Auth: the Public Key is the username and the Private Key is the password (both generated under Partner > Settings > Integrations > API in the CloudRadial portal). This matches how the existing CloudRadial integration on app.mspbots.ai is configured (authType: 0, custom Key/Secret credential fields) — this server receives both values per request via headers and never persists them.

Related MCP server: Datto RMM MCP Server

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m cloudradial_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok", "service": "cloudradial-mcp", "transport": "http"}

No credentials are required for the health endpoint.

授权参数说明 (Authentication)

Every request to /mcp must include the following HTTP headers:

Missing either header returns 401 Unauthorized.

Environment Variables

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP / SSE)

• Headers: X-CloudRadial-Public-Key: <public_key> (required), X-CloudRadial-Private-Key: <private_key> (required)

Tool List

34 tools — full coverage of every operation in the official CloudRadial OpenAPI spec.

Company (1)

Article (3)

Feedback (3)

Token (3) — portal 合并字段变量,与鉴权无关

Archive & Archive Item (6)

FlexibleAsset — IT Glue 兼容层 (8)

FlexibleAssetType — 自定义资产类型定义 (8)

Metadata — OData v2 (2)

测试示例 (Test Example)

List companies:

{
  "method": "tools/call",
  "params": { "name": "cloudradial_get_companies", "arguments": { "take": 10 } }
}

Equivalent curl against the running server (streamable HTTP MCP endpoint):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-CloudRadial-Public-Key: <public_key>" \
  -H "X-CloudRadial-Private-Key: <private_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "cloudradial_get_companies", "arguments": { "take": 10 } }
  }'

API Reference

• Getting started: https://developers.cloudradial.com/docs/getting-started

• Swagger UI: https://api.us.cloudradial.com/swagger

• Base URL: https://api.us.cloudradial.com

Known Gaps / Not Yet Verified

• Not yet tested against a live CloudRadial account — only protocol-level verification (health check, 401 on missing credentials, tools/list returning all 34 tools) has been done so far.

• cloudradial_create_archive_item's request body shape is not published in CloudRadial's OpenAPI spec (the schema is empty) — CloudRadial's docs describe archive item uploads via drag-and-drop, an archive-unique email address, or "an API connection" (up to 128MB), but do not document the exact JSON field names. Verify the correct payload shape with CloudRadial support or by inspecting a successful portal-side upload before relying on this tool in production.

• The Token API (cloudradial_get_tokens/cloudradial_set_token/cloudradial_delete_token) manages CloudRadial's portal merge-field variables (@-prefixed tokens used in Articles/Automations/Messages) — it is unrelated to authentication, despite the name.

• The FlexibleAsset/FlexibleAssetType tools wrap a JSON:API-shaped, IT Glue-compatible layer (/compatibility/...); bulk update/create-under-organization tools accept pre-shaped JSON:API list payloads rather than fully flattened arguments, since the nesting (data[].attributes.{...}) doesn't flatten cleanly into named parameters.

• cloudradial_query_odata accepts a raw OData query string rather than typed parameters, since the spec does not declare $filter/$select/etc. as typed Swagger parameters (standard for OData v4 endpoints).