Skip to Content
IoT アプリ開発IronFlock APIMCPエンドポイント

MCPエンドポイント

IronFlockはMCPサーバーです。Claudeや、Model Context Protocolを話すその他のクライアントは、APIキーが許可する範囲で、プロジェクトの一覧を取得し、そのデバイス、アプリ、データを読み取り、IronFlockが提供するツールでそれらを操作できます。このエンドポイントはREST APIと同じAPIサービスの一部で、同じAPIキーを使います。

アドレスと認証

IronFlockクラウドでのURLhttps://api.ironflock.com/mcp
アプライアンスでのURLhttps://api.にアプライアンスのドメイン、続けて/mcp。アプライアンスがIronFlock APIサービスを実行するようになってから利用できます
トランスポートStreamable HTTP
認証Authorization: Bearer <your API key>

APIキーは、APIキーの作成の説明に従ってStudioで作成します。すべてのリクエストにキーが付きます。キーのないリクエスト、または有効でないキー(削除済み、期限切れ、別のIronFlockのもの)を使ったリクエストには、HTTP 401が返されます。サーバーはブラウザーによるサインイン(OAuth)を提供していません。キーが唯一の入り口です。

サーバーはセッションを保持しません。各リクエストは個別に処理されるため、クライアントは自由に接続、切断、再接続できます。サーバーはすべてのリクエストに1つのJSON本文で応答し、購読するイベントストリームはありません。

Claudeを接続する

キーは、Claude自身の設定に自分で入力します。チャットには絶対に貼り付けないでください。

Claude Code

Claude Codeは、IronFlockのMCPサーバーを宣言するironflockプラグインを通じて接続します。ターミナル、IDE拡張機能、Claudeデスクトップアプリの「Code」タブで動作します。

  1. Claude Codeのセッションでマーケットプレイスを追加し、プラグインをインストールします:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. インストールすると、2つの設定を含むダイアログが開きます。IronFlock API address は、クラウドではhttps://api.ironflock.com、アプライアンスではhttps://api.にアプライアンスのドメインを続けたものです。どちらの場合も/mcpと末尾のスラッシュは付けません。IronFlock API key は、Studioで作成したキーです。Claude Codeはキーを設定ファイルではなく、システムの安全な認証情報ストアに保存します。

  3. Claude Codeを再起動します。すると/mcpに、サーバーplugin:ironflock:ironflockが接続済みとして表示されます。

設定は後から/plugin configure ironflock@ironflockで変更し、Claude Codeを再起動します。キーが設定されるまで、サーバーは起動しません。シェルからのインストール(claude plugin install)ではダイアログが開かないため、セッション内で/plugin configure ironflock@ironflockを使って設定を完了してください。プラグインとそのスキルについては、Claude Codeで開発で説明しています。

Web、デスクトップ、スマートフォンのClaudeとCowork

プラグイン自体の接続が使えるのはClaude Codeだけです。ClaudeアプリのチャットとCoworkでは、キーをリクエストヘッダーとして持つカスタムコネクタとして、IronFlockを一度追加します。カスタムコネクタのリクエストヘッダーはベータ機能で、一部の組織でのみ利用できます。以下のダイアログに Request headers セクションがない場合、組織ではまだこの機能を利用できず、現時点ではそこにIronFlockを接続できません。Claude Codeは使えます。

  1. Customize > Connectors を開き、Add、次に Add custom connector を選びます。
  2. 名前にIronFlock、サーバーURLにhttps://api.ironflock.com/mcpを入力します。
  3. Authentication を No sign-in に設定します。
  4. Request headers で、ヘッダーAuthorizationを追加し、値にBearer とキーを続けて入力します。Bearerという語、半角スペース1つ、そしてキーです。Bearer がないと、IronFlockはリクエストを拒否します。
  5. Add を選びます。

TeamプランとEnterpriseプランでは、オーナーが Organization settings > Connectors で Add、次に Custom を選んでコネクタを追加します。リクエストヘッダーは Advanced の下にある場合があります。そのコネクタを使う全員が、オーナーが入力した1つのキーで操作するため、全員が使ってよいスコープとプロジェクトだけをキーに与えてください。

コネクタのリクエストヘッダーは編集できません。キーを変更するには、コネクタを削除して追加し直します。コネクタはAnthropicのサーバーから接続するため、アドレスはインターネットから到達できる必要があります。クラウドはこの条件を満たします。社内ネットワークからしか到達できないアプライアンスは、通常そこでは接続できませんが、そのネットワーク内のコンピューターで動くClaude Codeなら接続できます。

その他のMCPクライアント

Streamable HTTPとリクエストヘッダーをサポートするクライアントであれば、URLとヘッダーAuthorization: Bearer <your API key>で接続できます。共有するファイルやコミットするファイルにキーを含めないでください。

接続を確認する

ClaudeにIronFlockのプロジェクトの一覧を取得させ、続いてそのうちの1つのデバイスの一覧を取得させます。Claudeは、読み取りだけを行うlist_projectsとlist_devicesを呼び出します。

ツール

サーバーは、以下の分野で33個のツールを提供します。ほとんどのツールは1つのプロジェクト内で動作し、list_projectsが返すそのプロジェクトのswarm_keyを受け取ります。何かを変更または削除するツールにはその旨が示されているため、Claudeのようなクライアントは、呼び出す前にあなたに確認できます。

プロジェクト

ツールスコープ機能
list_projectsdevices:readキーが操作できるプロジェクトの一覧を取得します

デバイス

ツールスコープ機能
list_devicesdevices:readプロジェクトのデバイス、各デバイスにインストールされたアプリ、それらが動作しているかどうか、デバイスがオンラインかどうかの一覧を取得します
create_devicedevices:writeプロジェクトにデバイスを作成し、そのキーと名前を返します
delete_devicedevices:writeプロジェクトからデバイスを完全に削除します

プロジェクト内のアプリ

ツールスコープ機能
list_project_appsapps:readプロジェクトにインストールされたアプリと、それぞれが動作しているデバイスの数の一覧を取得します
check_app_statusapps:readアプリがデバイス上で動作しているか、データが届いているかを表示します
install_appapps:writeストアのアプリをプロジェクトにインストールし、必要に応じてデバイスにもインストールします
set_app_stateapps:writeインストール済みのアプリをデバイス上で開始または停止します
update_appapps:writeインストール済みのアプリを最新のリリースに更新します
uninstall_appapps:writeデバイスから、またはプロジェクト全体からアプリを削除します

アプリストアと費用

ツールスコープ機能
search_appsapps:read機能でアプリストアを検索し、一致するアプリを価格とともに返します
get_app_detailsapps:read1~3個のストアアプリの説明、README、価格を読み取ります
get_install_quoteapps:readアプリのインストールにかかる費用と、インストールを妨げる要因を調べます
estimate_project_costapps:readプロジェクト構成の年間費用を見積もります。何も購入されません
sync_app_to_storeapps:writeアプライアンスのみ:IronFlockクラウドストアのアプリを、アプライアンス自身のストアにコピーします

データ

ツールスコープ機能
get_schemadata:readプロジェクトのデータベースのテーブル、ビュー、カラムを説明します
execute_sqldata:readプロジェクトのデータベースで、読み取り専用のSELECTクエリを1つ実行します
list_dashboardsdata:readプロジェクトのダッシュボードの一覧を取得します
list_app_filesdata:readアプリがプロジェクトに保存したファイルの一覧を取得し、検索します
read_app_filedata:readアプリが保存したファイル(テキスト、画像、その他のファイル)を1つ読み取ります
save_transformdata:writeボード向けに派生値を常に最新に保つカスタム変換を作成または置き換えます
delete_transformdata:writeカスタム変換を完全に削除します

アラーム

ツールスコープ機能
list_alarmsalarms:readプロジェクトのアラームを、状態、トリガー、受信者とともに一覧表示します
create_alarmalarms:writeアプリのデータテーブルを監視するアラームを作成します
update_alarmalarms:writeアラームのトリガーや受信者を変更し、またはアラームを一時停止、再開します
delete_alarmalarms:writeアラームをその履歴とともに完全に削除します

ログと監査ログ

ツールスコープ機能
get_app_logslogs:readアプリ自身のログ出力を、アプリが動作しているデバイスから読み取ります
get_device_logslogs:readデバイス自身が行ってきたこと(アプリ、ダウンロード、ディスク、ネットワーク、エージェントの更新)を読み取ります
query_audit_loglogs:read監査ログに対して読み取り専用のクエリを1つ実行します。誰がいつプロジェクト、そのデバイス、グループ、アプリを変更したかがわかります
get_appliance_healthdevices:readアプライアンスのみ:アプライアンス自身のプラットフォームサービス、ディスク、メモリ、ライセンス、更新の状態を確認します
get_appliance_logslogs:readアプライアンスのみ:アプライアンスのプラットフォームの一部分のログを読み取ります

アプリのツール

アプリは、AIエージェントとともに独自のツールを提供します。これは、マシンの状態を読み取る、設定を変更するなど、デバイス上で動作するアプリの機能です。これらには2つのツールでアクセスします。

ツールスコープ機能
list_app_toolsapptools:callインストール済みのアプリのツールを、引数とアプリのエージェントの指示とともに一覧表示します
call_app_toolapptools:callそのうちの1つを、プロジェクトの1台のデバイス上で実行します

call_app_toolはデバイス上で動作し、アプリのツールはそこで変更を加えることがあります。デバイスは、キーの所有者から見えるプロジェクトのデバイスでなければならず、所有者には、ボードからアプリを操作する場合と同様に、アプリのデータを使用する権限が必要です。アプリが受け取るのは指定した引数だけで、それ以外は何も受け取りません。一覧に表示されるのはインストール済みのリリースのツールだけで、アプリの開発バージョンのツールは表示されません。ツールのテキストはアプリの開発者が書いたもので、一定の長さで切り詰められます。

スコープ

各ツールには、上の表に示した1つのスコープが必要です。サーバーはクライアントに、キーが使えるツールだけを提供し、それ以外のツールは存在しないものとして拒否します。キーが何を許可していても、ツールがキーの所有者がIronFlockで実行できる以上のことを行うことはありません。releases:publishに対応するツールはありません。これはリリースをビルドするREST操作のためのスコープです。すべてのスコープについてはスコープを、Studioでスコープを選ぶ方法についてはAPIキーの作成を参照してください。

プロジェクトに制限されたキーには、それらのプロジェクトだけが見えます。1つのアプリに制限されたキーには、アプリのために動作するツールだけが提供されるため、list_projectsは提供されません。どちらのキーにも、1つのプロジェクトを超えるツールは提供されません。つまり、所有者が読めるあらゆるプロジェクトのアセットをクエリで指定できるquery_audit_log、どのプロジェクトにも属さない2つのアプライアンスツール、そしてアプライアンスのストアを全員に対して変更するsync_app_to_storeです。

一部のツールには追加のルールがあります:

  • install_appは、あなたに提示されたget_install_quoteの回答を受け取り、その見積もり以降に価格やその他の内容が変わっていれば何もインストールしません。有料アプリのインストールには費用がかかります。
  • set_app_stateとupdate_appが1回の呼び出しで変更するデバイスは最大10台です。
  • create_deviceは新しいデバイスのキーと名前を返しますが、デバイスの認証情報を含む設定ファイルは決して返しません。このファイルは、Studioのデバイス設定の メンテナンス > デバイス設定ファイル > 設定ファイルをダウンロード からダウンロードするか、デバイスを作成してファイルをマシン上に保持するironflock agent install --project <project> --name <name>を使ってマシン上でデバイスをセットアップしてください(ログインとデバイスの管理)。
  • プロジェクトが保存できるカスタム変換は一度に1つです。最初のsave_transformの実行中に2つ目を呼び出すと拒否されます。
  • アカウントがquery_audit_logを実行できるのは、同時に1回まで、1分間に6回までです。背後のデータベースが共有されているためです。
  • 呼び出しの時間内に完了しなかった変更も、実行されている可能性があります。結果にその旨が示され、ツールが変更を繰り返すことはありません。

結果

結果はJSONで、構造化コンテンツとして、また同じJSONをテキストブロックとして返されます。長い一覧は50,000文字に収まるように切り詰められ、そのcutメンバーが、省略されたエントリの数と続きを読む方法を示します。画像(PNG、JPEG、GIF、WebP)は画像として、PDFなどのその他のファイルはメディアタイプ付きの埋め込みリソースとして返されます。

ツールが要求されたことを実行できない場合、その結果はエラーとしてマークされ、理由が1文で示されます。例えば、プロジェクトが存在しない、プラットフォームが時間内に応答しなかった、などです。

上限

APIキーごとの既定値は次のとおりです:

上限
リクエスト1分間に120件、バーストは最大30件
同時に開いているリクエスト8
リクエスト本文1,114,112バイト:1 MiBの引数と、それを包むメッセージ
1回のツール呼び出し90秒
データベースクエリ30秒。execute_sqlは、より多くを要求しない限り100行、最大1,000行を返します
1つの結果50,000文字。call_app_toolの結果は45,000文字で切り詰められます

エラー

応答意味対処
401キーがない、入力ミスや途切れがある、削除済み、期限切れ、または別のIronFlockのもの。コネクタではBearer が抜けている可能性があります接続先のIronFlockのStudioで新しいキーを作成し、入力し直します
/mcpでの404アドレスに/mcpが2回含まれている、またはインスタンスがまだエンドポイントを提供していない(IronFlock APIサービスを実行していないアプライアンスなど)アドレスを修正します。それ以外の場合はクラウドを使います
405/mcpへのGETとDELETE:サーバーにはイベントストリームも、終了するセッションもありませんPOSTを使います
413リクエスト本文が大きすぎる1回の呼び出しで送る量を減らします
429キーのリクエストが多すぎる、または同時に開いているリクエストが多すぎる。Retry-Afterヘッダーが待つべき秒数を示しますその時間だけ待ち、同時に行う呼び出しを減らして続行します
503プラットフォームが現在利用できない、またはサービスがシャットダウン中1分後にもう一度試します
504プラットフォームが時間内に応答しなかった1分後にもう一度試します

要求されたことを実行できないツールは、HTTPエラーでは応答しません。その結果がエラーとしてマークされ、何が問題だったかを1文で説明します。

キーを安全に保つ

  • キーをチャットに絶対に貼り付けないでください。貼り付けた場合、キーはその会話の一部になっています。Studioでキーを削除し、新しいキーを作成して設定に入力してください。
  • Studioが新しいキーを表示するのは、作成時の1回だけです。すぐにクライアントの設定に保存してください。
  • キーを使う場所ごとに1つのキーを使えば、ほかのキーに影響を与えずに1つだけを削除できます。使わなくなったキーは削除してください。キーの有効期間は1年です。
  • キーには、Claudeが必要とするスコープとプロジェクトだけを与えてください。すべてのプロジェクト で すべて を実行できるキーを使うと、ClaudeはあなたがIronFlockで実行できることをすべて実行できます。何かを変更または削除するツールにはその旨が示されているため、Claudeのようなクライアントは先にあなたに確認できます。同意する前に、Claudeが何を変更しようとしているかを読んでください。
  • 組織で共有するコネクタは、すべてのユーザーに対して1つのキーで動作します。全員が見てよいものだけを見られるアカウントのキーを使ってください。
Last updated on