covedataprotection-mcp

Cove Data Protection(N-able のバックアップ/BDR プラットフォーム。旧称 N-able Backup / Backup Manager)向けの MCP サーバー。Backup Manager JSON-RPC Management Service API を MCP ツールとして公開します。

概要

• ステートレスな HTTP サービスです。認証情報が永続化されることは一切ありません。各リクエストはヘッダー経由で独自の認証情報を提供し、その認証情報は単一リクエストの期間中のみ使用されます。

• 同時リクエストをサポートします。リクエストごとの認証情報の分離は、グローバル/共有のクライアントインスタンスではなく、Python の contextvars によって行われます。

• エントリポイント: POST /mcp(MCP プロトコル)と GET /health(ヘルスチェック)。

• デフォルトポート: 8080(MCP_HTTP_PORT で設定可能)。

Related MCP server: spanning-mcp

範囲

26 ツール。元となる 247 ツールのフルスキーマビルド(2026-08-04)から削減したものです。MSPbots 自身の Cove Data Protection 統合(本番プラットフォームに対して /web/int/sys/integration/api/list で稼働確認済み)は正確に 6 つの API で構成されており、以下の JSON-RPC メソッドにマッピングされています:

上記の確認済みの実在メソッド 5 つはそのまま維持し、さらにそれらが扱う 3 つのリソースタイプそれぞれに対する同カテゴリのコア CRUD(Add/Get/Modify/Remove)を追加しました — accounts(9 ツール)、partners(9 ツール)、users(7 ツール)— さらに GetServerInfo(1 ツール、接続セルフテスト用で、後述の当初のライブ検証に使用)を追加しています。元の 247 ツールビルドの他のすべてのカテゴリ(notifications、storage_nodes、contacts、storage、view_delivery、labels、jobs、custom_columns、branding、products、eula、locations、countries、audit、email、regions、features、permissions、templates — 19 カテゴリ、約 221 ツール)は、MSPbots が使用しておらず、このサーバーの目的の範囲外であるため、完全に削除しました。

認証

Cove には静的な長期有効な API キーがありません。その代わり、すべてのセッションは Login 呼び出し(partner + username + password)で始まり、これが短期間有効な visa トークン(有効期間約 15 分)を返します。このトークンは後続のすべての呼び出しに付随させる必要があります。

このサーバーはリクエスト間で visa をキャッシュしません。キャッシュすることはセッション状態の永続化を意味し、「認証情報を永続化しない」という要件と矛盾するためです。その代わり、api_client.CoveClient.call() はすべてのツール呼び出しで新しい Login を実行し、取得した visa はその後破棄します。呼び出しごとに HTTP ラウンドトリップが 1 回余分にかかる代わりに、完全なステートレス性を実現しています。

ヘッダー認証パラメータの説明

3 つのヘッダーのいずれかが欠けている場合、401 を返します:

{
  "error": "Missing credentials",
  "message": "This server requires the X-CoveDataProtection-Partner, X-CoveDataProtection-Username, and X-CoveDataProtection-Password headers",
  "required_headers": ["X-CoveDataProtection-Partner", "X-CoveDataProtection-Username", "X-CoveDataProtection-Password"],
  "optional_headers": []
}

環境変数

MCP エンドポイント

• POST /mcp — MCP プロトコル(ストリーミング可能な HTTP トランスポート)

• GET /health — ヘルスチェック。正確に {"status": "ok"} を返します(純粋なローカル liveness プローブであり、Cove API は呼び出しません)

ツール一覧

ツール名は covedataprotection_<snake_case_method_name> の形式に従います。たとえば、JSON-RPC メソッド EnumerateAccountStatistics は covedataprotection_enumerate_account_statistics になります。パラメータ名は JSON-RPC メソッド自身のパラメータ名(camelCase → snake_case)を反映しています。複雑な struct/enum 型のパラメータは dict/str として受け付け、ベンダー API にそのまま渡されます。実際に何を意味するかは 既知のギャップ を参照してください。

テスト例

# 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-CoveDataProtection-Partner: <your-partner-name>" \
  -H "X-CoveDataProtection-Username: <your-username>" \
  -H "X-CoveDataProtection-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": "covedataprotection_get_server_info",
      "arguments": {}
    }
  }'

期待される動作: 有効な認証情報ではサーバーバージョンとともに 200 を返します。無効な認証情報では Login 呼び出し自体が失敗し、すべてのツールが構造化された JSON エラーエンベロープを返します。例:

{"error":{"code":"unauthorized","message":"<vendor error message>","retryable":false}}

code は固定値 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error のいずれかです。retryable は、同じ呼び出しを再試行すれば成功する可能性があるかどうかを呼び出し元に示します(rate_limited と upstream_error の場合のみ true)。ツールはビジネス/ベンダーエラーに対して例外を発生させません。このエンベロープが通常のツール結果文字列として返されます。

ライブ検証済み (2026-07-29): covedataprotection_get_server_info (パラメータなし) が、この実行中のサーバーを通じて実際のパートナー/ユーザー名/パスワードでエンドツーエンドに呼び出され、実際のCoveサーバーバージョンを返しました。これにより、Login → visa → メソッド呼び出しのパイプラインが構造的にだけでなく、ライブAPIに対して機能することが確認されました。

APIリファレンス

• はじめに: https://developer.n-able.com/n-able-cove/docs/getting-started

• 認証: https://developer.n-able.com/n-able-cove/docs/authorization

• 呼び出しの構築: https://developer.n-able.com/n-able-cove/docs/construct-a-json-rpc-api-call

• 全メソッド/構造体/列挙型スキーマ (JSON): https://documentation.n-able.com/covedataprotection/Schema_23.3.json

既知のギャップ

• 2026-08-04に247ツールから26ツールに削減。 元のビルドはManagement Serviceスキーマのすべてのメソッドをカバーしていました。後のスコープ決定により、MSPbots自身の本番統合設定が実際に呼び出すもの（app.mspbots.ai に対する /web/int/sys/integration/api/list でライブ検証済み、統合ID 2026570354981494786）と、同じカテゴリのコアCRUDに削減されました。正確なAPI→メソッドのマッピングと削除されたカテゴリの完全なリストについては、上記のスコープセクションを参照してください。削除された~221のツール（notifications, storage_nodes, contacts, storage, view_delivery, labels, jobs, custom_columns, branding, products, eula, locations, countries, audit, email, regions, features, permissions, templates）はこのビルドには一切含まれていません。将来のニーズでそのいずれかが必要になった場合、元のスキーマ（下記リンクの Schema_23.3.json）に正確なメソッドシグネチャがまだ記載されており、保持されているツールと同じ方法で再追加できます。

• これはManagement Serviceのみを対象としています。 CoveのGetting Startedガイドには、バックアップ/リストアのセッション統計を提供する、別の独立したReporting Service（{host}/repserv_json、ストレージノードごとに実行）が記載されています。MSPbots自身の設定は、このReporting Serviceに対して「Query Sessions」レポートを呼び出します。これは、このMCPが生成元とするManagement Serviceスキーマの一部ではなく、Reporting Serviceの公開スキーマも見つかりませんでした。これが、このMCPがカバーしないMSPbots設定の唯一のエンドポイントです。Reporting Serviceのメソッドリスト/スキーマが利用可能になれば追加できます。

• 複雑な構造体/列挙型パラメータは完全にモデル化されておらず、型なし（dict/str）です。 スキーマは106の構造体と78の列挙型を定義しています。機械的に生成されたサーバーで、それぞれを型付きPythonパラメータとして完全に再現することはスコープ外でした。呼び出し元は、これらのdict引数をベンダーのスキーマに合わせて整形する必要があります（正確なフィールド名については Schema_23.3.json のStructsセクションを参照）。各パラメータの説明には、対応する構造体の名前と、そのスキーマファイルへの参照が記載されています。

• visaキャッシュなし — 上記の認証セクションを参照してください。すべてのツール呼び出しは独自のLoginを実行します。これはシンプルで完全にステートレスですが、ツール呼び出しごとにベンダーへのHTTPリクエストが1回ではなく2回になることを意味します。

• 26のツールはすべて、ベンダー自身のスキーマファイルから直接コード生成されたものであり、手書きではありません。パラメータ名/型はそのスキーマの正確さに依存します。covedataprotection_get_server_info はエンドツーエンドでライブ検証された唯一のツールです。残りは構造的に正しい（スキーマ検証済み、MCPプロトコルのtools/list確認済み）ものの、実際のデータに対する個別のスモークテストは行われていません。

ベンダーMCP SOP準拠に関する注記

• ツール数（26）はSOPの「≤20であるべき」というガイドラインを超えています。 すでに247→26に削減済み（上記参照）。残りの26は、3つのリソースドメイン（accounts/partners/users）にわたる個別のJSON-RPCメソッドに1:1で対応しており、必須パラメータの区別を失わずに統合することはできません（例：get_*_info（名前+パスワード）と get_*_info_by_id（数値ID）は、オプションパラメータを持つ同じツールではなく、異なるルックアップキーです）。

• どのツールにも limit / page_size スカラーパラメータは存在しません。 26のメソッドのいずれも、第一級の数値ページサイズパラメータを公開していません。ページネーション形状の唯一のフィールド（EnumerateChildPartners の range）は、そのまま渡される不透明なベンダー構造体であり、GetPartnerTree の children_limit も同様に解釈されずにベンダーに直接渡されます。このサーバーがSOPのデフォルト50/ハードキャップ200のガイダンスに対してクランプするものはありません。ベンダースキーマの range/limit構造体に独自の文書化されたページあたりの最大値があることが判明した場合は、SOPの汎用フォールバック上限ではなく、ここでそれを強制する必要があります。

• 資格情報の環境変数フォールバックなし。 config.Settings には partner/username/password フィールドがありません。get_client_from_context は、リクエストごとのcontextvarが未設定の場合、None（→ not_configured エンベロープ）を返します。環境変数にフォールバックするコードパスはありません。

• ツール注釈: すべての読み取りツール（get_*, enumerate_*）は readOnlyHint=True, idempotentHint=True とマークされています。add_* ツールは readOnlyHint=False, idempotentHint=False（2回作成することはno-opではありません）。modify_*/set_*/remove_* ツールは readOnlyHint=False, destructiveHint=True, idempotentHint=True です。