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 16 tools across 5 resource groups (Company, Article, Feedback, Token, Archive/ArchiveItem), trimmed down on 2026-08-04 from an original 34-operation full-API build (which additionally covered FlexibleAsset, FlexibleAssetType, and the OData v2 metadata endpoint). MSPbots' own stored integration config for this vendor calls exactly those 5 kept resource groups (confirmed via web/int/sys/integration/api/list against integration id 1579382881663623169: Company, Article, Feedback, Token, Archive, Archive Item) — all 16 tools in those groups were already tight core CRUD (get/create/delete, no bloat), so no per-tool trimming was needed within them; FlexibleAsset, FlexibleAssetType, and OData (18 tools total) were removed entirely as unused by MSPbots. If a removed group is needed later, the vendor's OpenAPI spec (linked below) still documents its exact operations and they can be re-added the same way the kept tools were generated. 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.

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

16 tools, trimmed down from an original 34-operation full-API build (2026-08-04) — see Overview above for the exact rationale.

Company (1)

Article (3)

Feedback (3)

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

Archive & Archive Item (6)

测试示例 (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

• Trimmed from 34 to 16 tools on 2026-08-04. The original build covered every operation in the official OpenAPI spec. A later scope decision cut this back to MSPbots' actually-used 5 resource groups (Company, Article, Feedback, Token, Archive/ArchiveItem) — see Overview above for the exact rationale. FlexibleAsset, FlexibleAssetType, and the OData v2 metadata endpoint (18 tools total) were removed entirely as unused. If a removed group is needed later, the vendor's OpenAPI spec (linked below) still documents its exact operations and they can be re-added the same way the kept tools were generated.

• Not yet tested against a live CloudRadial account — only protocol-level verification (health check, 401 on missing credentials, tools/list returning all 16 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.