addigy-mcp

Addigy MCP server — exposes both Addigy API generations (v2 and the legacy v1) as MCP tools.

Naming note: app.mspbots.ai has two separate Addigy integrations: "Addigy" (subject_code = ADDIGY, legacy v1 API, auth via Site + Client ID + Client Secret) and "Addigy V2" (subject_code = ADDIGYV2, v2 API, auth via a single API Key). This single server implements both, since they are the same vendor product and MSPbots' own integrations still use both API generations.

Overview

This server implements the Model Context Protocol (Streamable HTTP/SSE transport) and covers the interfaces that MSPbots' own Addigy integrations actually use, matching the interface scope configured in MSPbots' sys_integration/sys_integration_api tables:

It follows the MSPbots Vendor MCP Service SOP: stateless, no stored credentials, per-request header authentication.

• Addigy API v2 authenticates via a single static API Key (x-api-key header), created in the Addigy console under Account → Integrations — matching the single "API Key" field configured in MSPbots' Addigy V2 integration.

• Addigy API v1 (legacy, superseded by v2 but still in use for capabilities not yet in v2) authenticates via client_id + client_secret query parameters against a per-organization Site domain — matching the Site/Client ID/Client Secret fields configured in MSPbots' legacy Addigy integration.

This server forwards caller-supplied credentials as-is for whichever API generation a tool call targets; it never stores or persists them. A caller only needs to send the header set for the API version it actually calls — v1 and v2 credentials are independent.

Related MCP server: Meraki MCP Server

Quick Start

Docker (recommended)

docker compose up --build

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

Local (uv)

uv sync
python -m addigy_mcp

Health Check

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

No credentials are required for the health endpoint.

授权参数说明 (Authentication)

Every request to /mcp must include either the v2 header or all three v1 headers (a caller wanting both API generations sends all four):

Missing both the v2 header and a complete v1 header set returns 401 Unauthorized. Calling a v1 tool with only v2 credentials (or vice versa) returns a clear per-tool error rather than a blanket 401, so a caller using only one API generation doesn't need to send the other's headers at all.

Environment Variables

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP / SSE)

• Headers: X-Addigy-Api-Key: <api_key> and/or X-Addigy-V1-Client-Id + X-Addigy-V1-Client-Secret + X-Addigy-V1-Site

Tool List

11 tools total (5 v2 + 6 v1), matching the exact combined interface count MSPbots' "Addigy" and "Addigy V2" integrations use.

Addigy V2 (5)

multitenancy/child_organizations apply to the three /oa/... endpoints and control whether results include descendant (child) organizations, per Addigy's "Child Organizations" API convention.

Addigy v1 — legacy (6)

测试示例 (Test Example)

v2 — Query policies:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Addigy-Api-Key: <api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "addigy_query_policies", "arguments": {} }
  }'

v1 — List devices:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Addigy-V1-Client-Id: <client_id>" \
  -H "X-Addigy-V1-Client-Secret: <client_secret>" \
  -H "X-Addigy-V1-Site: prod.addigy.com" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "addigy_v1_get_devices", "arguments": { "page": 1, "per_page": 50 } }
  }'

A parameterized v2 call:

{
  "method": "tools/call",
  "params": {
    "name": "addigy_get_alerts",
    "arguments": { "page": "1", "per_page": "50" }
  }
}

API Reference

• v2 documentation: https://api.addigy.com/api/v2/documentation/ — auth via x-api-key header

• v1 documentation: https://documenter.getpostman.com/view/6033495/S17tPnJf — auth via client_id/client_secret query parameters against a per-organization Site domain (the currently published Postman doc only shows a subset of v1 endpoints; the 6 v1 tools here are grounded in MSPbots' own sys_integration_api records of method/path/params for the legacy "Addigy" integration)

Known Gaps / Implementation Notes

• Scope is intentionally limited to the interfaces MSPbots' "Addigy" and "Addigy V2" integrations are configured to use (5 + 6 = 11), not the full Addigy v2 API surface (which spans 300+ endpoints across MDM commands, policies, benchmarks, scripts, webhooks, and many third-party integration passthroughs).

• page/per_page on addigy_get_alerts (v2) are typed as strings because the vendor's own OpenAPI spec defines them as type: string (despite being numeric page/size values) — passed through as-is.

• v1 credentials (client_id/client_secret) are sent as query-string parameters, matching the pattern shown in Addigy's own v1 Postman examples (e.g. "Get Public Software", "Get Specific Custom Software") — Addigy's v1 API is inconsistent about this across endpoints (some examples use headers instead), so this should be verified against a live v1 account on first use.

• Not yet tested against a live Addigy account (either API generation) — only protocol-level verification (health check, 401 when neither credential set is present, correct per-tool error when only one credential set is present, tools/list returning all 11 tools) has been done so far.