IT Management Remote MCP のエラーと制限

IT Management Remote MCP のエラーには、HTTP のエラーとツールの実行エラーの 2 種類があります。

認証ヘッダーやリクエストの形式が誤っていると、サーバーは MCP の処理を始める前に HTTP のエラーを返します
ツールの引数や IT Management API の呼び出しでエラーが起きると、サーバーはツールの結果としてエラーを返します

エラーレスポンスの形式

HTTP のエラー

サーバーは、error（エラーの識別子）と message（説明）を持つ JSON を返します。

{
  "error": "unauthorized",
  "message": "Missing X-Admina-Organization-Id header."
}

ツールの実行エラー

HTTP のステータスは 200 のまま、ツールの結果に isError: true が付きます。エラーの内容は content のテキストに入ります。

{
  "content": [
    {
      "type": "text",
      "text": "Invalid input:\nidentityIds: Array must contain at most 50 element(s)"
    }
  ],
  "isError": true
}

HTTP ステータスコード

ステータスコード	`error`	主な原因
400	`invalid_organization_id`	`X-Admina-Organization-Id` の値に、英数字・`_`・`-` 以外の文字が含まれている、または 65 文字以上ある
400	`invalid_json`	リクエストボディが JSON として読めない
401	`unauthorized`	`Authorization` ヘッダーが `Bearer <API_KEY>` の形式ではない、または `X-Admina-Organization-Id` ヘッダーが無い
404	`not_found`	存在しないパスにリクエストした
405	`method_not_allowed`	`POST` 以外のメソッドでリクエストした
413	`payload_too_large`	リクエストボディが 1 MB を超えている
429	—	リクエスト数の上限を超えた（制限の内容）
500	`internal_error`	サーバー内部でエラーが発生した

Authorization ヘッダーが無いリクエストは、サーバーに届く前にロードバランサーが拒否します。このときの 401 は JSON ではなく、401: Missing Authorization bearer token. というテキストです。 429 も JSON ではなく、テキストで返ります。

主なエラー

ツールの実行エラーは、テキストの先頭で種類を見分けられます。

テキストの先頭	意味
`Invalid input:`	引数が入力スキーマ（`inputSchema`）に合っていません。続く行に、問題のある引数とその理由が入ります
`Admina API error:`	IT Management API がエラーを返しました。続けてエラーの識別子（`errorId`）が入り、詳細がある場合は `Details:` の後に入ります
`Unknown tool:`	存在しないツール名を指定しました
`Error:`	上記以外のエラーです

Admina API error: で返る主なエラーは次のとおりです。

主な原因	エラーの識別子
API キーが無効、組織 ID が API キーの組織と一致しない、組織が有効な状態ではない	IT Management API の認証エラー
API キーの作成者が組織から削除された	`api_key_creator_removed`
組織で有効になっていない機能のツールを呼び出した	`im_a_teapot`

ツールの一覧には、組織で有効になっていない機能のツールも表示されます。そのツールを呼び出すと、Admina API error: im_a_teapot が返ります。

エラーへの対処

401 や認証エラーが返る場合は、サポートの確認事項を順に確かめてください
Invalid input: が返る場合は、表示された引数を入力スキーマに合わせて直してください
429 が返る場合は、しばらく待ってからやり直してください
413 が返る場合は、1 回で送るデータを減らしてください。まとめて処理するツールは、件数を分けて複数回呼び出してください

制限の内容

対象	制限
リクエスト数	1 つの IP アドレスにつき、1 分あたり 600 リクエストまで
リクエストボディのサイズ	1 MB まで
`bulk_update_identities` の `identityIds`	50 件まで
`merge_identities` の `merges`・`identityMerges`	それぞれ 50 件まで
`unmerge_identities` の `peopleIds`・`identityIds`	それぞれ 50 件まで
`save_custom_accounts` の `create`・`update`・`delete`	合計 200 件まで

ツールは内部で、接続に使った API キーで IT Management API を呼び出します。そのため、IT Management API のレート制限も適用されます。ツールが送るリクエストは、IT Management API を直接呼び出した場合と同じように数えられます。 1 回のツールの呼び出しで、複数のリクエストを送ることがあります。たとえば merge_identities に identityMerges を指定すると、従業員の ID を調べるリクエストを追加で送ります。

制限を超えたときの応答

1 分あたりのリクエスト数を超えると、HTTP ステータス 429 と 429: Too many requests. というテキストが返ります。 IT Management API のレート制限を超えた場合は、ツールの実行エラー（Admina API error:）として返ります。

制限を超えないための工夫

一覧のツールは limit で 1 回に取得する件数を調整し、必要なページだけを取得してください
複数の従業員に同じ更新をする場合は、update_identity を繰り返さずに bulk_update_identities を使ってください
非同期で実行されるツールの結果を確認するときは、間隔を空けて確認してください

はじめに

ガイド

ヘルプ

リファレンス

IT Management Remote MCP のエラーと制限

エラーレスポンスの形式

HTTP のエラー

ツールの実行エラー

HTTP ステータスコード

主なエラー

エラーへの対処

制限の内容

制限を超えたときの応答

制限を超えないための工夫

関連ページ

​エラーレスポンスの形式

​HTTP のエラー

​ツールの実行エラー

​HTTP ステータスコード

​主なエラー

​エラーへの対処

​制限の内容

​制限を超えたときの応答

​制限を超えないための工夫

​関連ページ

エラーレスポンスの形式

HTTP のエラー

ツールの実行エラー

HTTP ステータスコード

主なエラー

エラーへの対処

制限の内容

制限を超えたときの応答

制限を超えないための工夫

関連ページ