コンテンツにスキップ
Calyx Help

MCP Apps

MCP Apps は、MCP サーバーのツールが結果と一緒に対話的なビューを返せるようにする仕組みです。 Calyx はそのサーバーを自分でホストします。 Settings でサーバーを一度追加すると、Calyx がそのサーバーに接続し、ツールをすべてのエージェント CLI に公開します。 ツールにビューが付いていれば、そのビューを、呼び出したエージェントのペインの隣にドックとして表示します。

Calyx が実装しているのは MCP Apps 拡張（io.modelcontextprotocol/ui）です。 サーバー側はツールに ui:// リソースを宣言し、Calyx はそのリソースをサーバーから読み取って、サンドボックス化した Web ビューに描画します。

前提条件

Section titled “前提条件”

MCP Apps は AI Agent IPC と同じサーバー上で動くため、Settings の Agents ペインにある Enable AI Agent IPC がオンになっている必要があります。 オフの間は MCP Apps ペインにその旨のバナーが出て、追加したサーバーにエージェントは到達できません。

スイッチがオンの間、Calyx は各エージェント（Claude Code、Codex、OpenCode、Hermes、Grok）の設定に、calyx-ipc のエントリと並べて calyx-mcp のエントリを書き込みます。 pi は設定ファイルを持たないため、代わりに Calyx の拡張に calyx_mcp ツールが加わります。 {"tool": "list"} を渡すと公開中のツールを一覧し、ツール名と args を渡すとそのツールを呼び出します。 すでに起動しているエージェントは、新しいエントリを読み込ませるために再起動してください。 0.43.0 より前のリリースから更新した場合も、追加の手順はありません。 スイッチがオンなら、Calyx は起動のたびにエントリを書き直します。

サーバーの追加

Section titled “サーバーの追加”

Settings（Cmd+,）を開き、MCP Apps ペインを選びます。 ホストされるのは、ここに並ぶサーバーだけです。 エージェント CLI が自分で接続しているサーバー（たとえば ~/.claude.json にあるもの）は、ここに追加するかインポートするまで対象になりません。

Add Server

Section titled “Add Server”

Add Server をクリックするとシートが開きます。

  • Name は Calyx がそのサーバーを表示するときの名前です。
  • Alias は、サーバーのツールを公開するときの短い接頭辞です（エージェントから見えるツールを参照）。編集するまでは Name に追従します。小文字一字に続けて最大 9 文字の小文字か数字で構成し、保存後は変更できません。
  • Transport は stdio か HTTP です。

stdio サーバーでは、Command、Arguments（スペース区切り。スペースを含む値は引用符で囲む）、必要なら Working directory を入力します。 Environment セクションにはプロセスに渡す環境変数を並べます。 入力した値は伏せ字で表示されます。

HTTP サーバーでは URL を入力します。 Streamable HTTP ではなく従来の HTTP+SSE トランスポートを使うサーバーには、Legacy HTTP+SSE server をオンにします。 一つのレスポンス、またはサーバーが開いたままにするストリーム上の一つのイベントは 64 MiB までで、それを超えるとエラーになります。 ストリームが運ぶデータの合計には、開いている期間にかかわらず上限がありません。 Headers セクションにはリクエストヘッダーを並べ、こちらも入力後は伏せ字になります。 OAuth セクションは、事前登録したクライアントでのサインインを求めるサーバーでだけ必要です。 Client ID、Client authentication（None、Client secret (POST)、Client secret (Basic)）、Client secret を入力します。 Use fixed redirect port 41890 をオンにすると、サインイン後のリダイレクト先がランダムなポートではなくこの固定ポートになります。 リダイレクトのポートを厳密に指定する必要がある認可サーバーでだけオンにしてください。

Import JSON

Section titled “Import JSON”

Import JSON は、エージェント CLI が自分の MCP サーバーのために使っている設定をそのまま取り込みます。 {"mcpServers": {...}} の形のオブジェクト、サーバーのマップ、単一のサーバーのいずれかを貼り付けます。 ${VAR} の参照は Calyx の環境変数で置き換えられます。

プレビューには、各サーバーのエイリアス、解決できなかった ${VAR}、Calyx が無視するキーが並びます。 エイリアスが重複するサーバーがあると When an alias is taken が表示され、Replace、Rename（標準）、Skip のいずれかを選びます。 選んだ扱いは、重複するすべてのサーバーに適用されます。

テキスト欄は入力をそのまま受け付けます。 引用符が曲がった引用符に置き換わることも、-- が一本のダッシュに変わることもないため、貼り付けた JSON も手で打った JSON もそのまま解析できます。

サーバーの行

Section titled “サーバーの行”

各サーバーの行には、有効と無効を切り替えるスイッチと、状態を示す一行があります。

  • Disabled、Connecting、N tools, M with UI、Sign-in required、Signing in、Disconnected (reconnecting) のいずれか
  • または失敗を説明する一文。stdio サーバーにエラー出力があれば、その末尾が続きます

その下にエイリアス、トランスポート、コマンドか URL が並び、サインイン済みのサーバーには Signed in が付きます。 ボタンは、状況に応じて Retry、Sign In、Cancel Sign-In、Sign Out、Edit、Remove が出ます。 Remove は確認なしに、サーバーと保存済みのシークレットを即座に削除します。

Details を開くと、除外されたツールの一覧とその理由、サーバーが送ってきた指示文が見られます。 タスクとしての実行（execution.taskSupport）を必要とするツールは除外されます。 Calyx はツールをタスクとして実行しないためです。

HTTP サーバーへのサインイン

Section titled “HTTP サーバーへのサインイン”

OAuth のチャレンジを返す HTTP サーバーの行には Sign-in required と表示されます。 Sign In をクリックすると、Calyx は既定のブラウザで認可ページを開き、ループバックインターフェイスで戻りのリダイレクトを待ちます。 サインインが済むと行は Signed in になり、そのサーバーのツールが使えるようになります。

サインインが必要なサーバーのツールをエージェントが呼び出すと、<server> requires sign-in と題したフローティングのプロンプトが Sign In と Cancel のボタンとともに表示されます。 ツール呼び出しは、サインインが終わるまで最長 2 分待ちます。

Calyx が名乗る OAuth クライアントは、次の順で決まります。

  1. Edit で入力した Client ID
  2. クライアント ID メタデータ文書（https://getcalyx.app/oauth/mcp-client.json）。認可サーバーがこの形式の登録に対応している場合
  3. その認可サーバーに対して Calyx がすでに行った動的登録
  4. 新しい動的クライアント登録（RFC 7591）。Calyx という名前のネイティブクライアントとして登録します

どれも使えないときは、その認可サーバーが自動のクライアント登録に対応していないこと、そこに登録済みの OAuth アプリのクライアント ID が必要なことが行に表示されます。 クライアント ID は Edit で入力します。

トークンとクライアントシークレットはログインキーチェーンに保存されます。 Sign Out はトークンをキーチェーンから削除します。 クライアントシークレットは、Edit で変更するかサーバーを削除するまで残ります。 サーバーへの失効要求は送りません。

エージェントから見えるツール

Section titled “エージェントから見えるツール”

Calyx は各サーバーのツールを自身の MCP エンドポイントで公開し、エージェントは calyx-mcp のエントリを通じてそこに到達します。 ツール名は <alias>-<tool> です。 Claude Code では mcp__calyx-mcp__<alias>-<tool> と表示されます。 48 文字を超える名前や、英数字と _ と - 以外の文字を含む名前は短縮され、短いハッシュが末尾に付きます。

これに加えて、二種類のツールが現れます。

  • app_context は、呼び出し元のペインで開いている MCP App ビューが最後に報告したコンテキストを返します。ビューでの操作内容をエージェントが読むためのツールです。
  • <alias>-app_<name> は、動作中のビュー自身が登録するツールです。そのビューを持つペインのエージェントにだけ見えます。

ツール呼び出しはサーバーへ転送され、結果はビューの有無にかかわらずエージェントに返ります。 Calyx がこれらの呼び出しに独自の承認プロンプトを挟むことはありません。 エージェント自身の許可プロンプトと、使っていれば承認のルーティングが、従来どおり適用されます。

アプリのビュー

Section titled “アプリのビュー”

ペインのエージェントがビュー付きのツールを呼び出すと、そのペインのターミナルの右側にドックが開き、ビューが表示されます。 ドックの幅は最初はペインの 40% です。 ターミナルとドックの間の区切り線をドラッグすると幅を変えられ、ドックが存在する間、Calyx はそのペインの幅を記憶します。 ドックはクイックターミナルでも動作し、永続セッションのペインは再接続をまたいでビューを保ちます。

各ビューはカードとして表示され、ヘッダーにはツール名、サーバー名、呼び出したエージェント名（show-map · map · claude-code）、Loading、Running、Completed などの状態、そして Close ボタンが並びます。 停止したビューや読み込めなかったビューには Reload が出ます。 一つのペインに複数のビューがあるときは、カードの上にセグメント式の切り替えが出ます。 動作中のビューを持つタブには、タブバーとサイドバーに小さなアクセントカラーの点が付きます（ツールチップは “An MCP App is running in this tab” です）。

アプリは別の表示モードを求めることがあります。 fullscreen はタブの分割領域全体をビューで覆います（ウィンドウ自体はそのままです）。 pip はビューをウィンドウ右下の小さなフローティングウィンドウへ移し、そのウィンドウを閉じるとビューはドックに戻ります。 モードを切り替える Calyx 側の操作はありません。 アプリが要求し、アプリが宣言したモードだけが使えます。

Calyx のペインで動いていないエージェント（たとえば別のターミナルで起動した CLI）が呼び出したビューは、代わりに独立したウィンドウで開きます。

ビューには Calyx の配色とフォントが渡されます。 ターミナルの背景色と前景色、フォントサイズ、アクセントカラー、ライトとダークの別が反映され、テーマを変えると追従します。

ビューが閉じるとき

Section titled “ビューが閉じるとき”

ビューは、Close をクリックしたとき、アプリ自身が終了を求めたとき、ペインを閉じたとき、Settings でサーバーを無効化または削除したときに取り除かれます。 呼び出したエージェントの会話が終わったときも取り除かれます。 Claude Code では /clear もこれに含まれます。 同じペインで新たにビュー付きのツールが呼ばれると、そのペインで終了済みのビュー（完了、キャンセル、リソースが不正で表示できなかったもの）は片付けられ、動作中のビューは残ります。

同意のプロンプト

Section titled “同意のプロンプト”

アプリが求めることのうち次の三つは、エージェントの許可プロンプトと同じ承認パネルを通ります。 いずれのプロンプトも、タイトルにサーバー名が入ります。

  • Open Link: アプリがブラウザで URL を開こうとしています。本文にはリンク全体が表示されます。Open は既定のブラウザで開き、Options には Always Allow for This View と Cancel があります。許可されるのは http、https、mailto のリンクだけです。
  • Send Message: アプリがエージェントへテキストを送り返そうとしています。Send は呼び出し元のペインにメッセージを貼り付けて送信し、Options には Always Allow for This View と Don’t Send があります。メッセージ内の画像は一時ファイルに保存され、代わりにそのパスが貼り付けられます。
  • Copy Message: アプリがメッセージを送ろうとしているものの、そのウィンドウにペインがありません。Copy はメッセージをクリップボードに置き、Options には Dismiss があります。

プロンプトを × で閉じた場合は Cancel か Don’t Send と同じ扱いになり、一時間応答がなかった場合も同様です。 同じビューから新しいプロンプトが来ると、保留中のものは置き換わります。 Always Allow for This View はそのビューが存在する間だけ有効で、Reload をまたいでも保たれ、ビューが取り除かれると忘れられます。 Auto-approve agent commands をオンにすることはありません。

承認パネルではなく専用のフローティングパネルを使う要求が二つあります。 サーバーが利用者に入力を求めるとき（elicitation）は、ウィンドウタイトルが <server> request、見出しが <server> asks のパネルに、Cancel、Decline、Accept の付いたフォームか、Cancel、Decline、Open の付いた URL が表示されます。 URL を開いた後は Done で閉じます。 アプリがファイルを渡そうとするときは、ファイルごとに macOS の保存パネルが開き、既定の保存先は ~/Downloads です。

ビューが到達できる範囲

Section titled “ビューが到達できる範囲”

ビューの HTML は MCP の接続を通じてサーバーから届きます。 Calyx が表示のために Web から何かを取得することはありません。 各ビューは非永続の Web ストアで動作し、ビューを閉じると破棄されます。 ページが自分で別のページへ移動したり、ウィンドウを開いたり、ダウンロードを始めたりすることはできず、カメラ、マイク、位置情報は決して許可されません。 ビューに提供される権限は、クリップボードへの書き込みだけです。

ビュー内からのネットワークアクセスは、サーバーがそのビューに宣言したドメイン（https か wss。http と ws はループバックに限る）に限られます。 何も宣言しないサーバーのビューは、外部へのリクエストを一切行いません。 すべてのホストを指すワイルドカードなど、Calyx が受け入れられない項目は除外され、カードのヘッダーに Ignored CSP entries として列挙されます。

保存される情報

Section titled “保存される情報”
  • サーバーの一覧は ~/Library/Application Support/Calyx/mcp-servers.json に保存され、利用者本人だけが読めます。
  • 環境変数の値、ヘッダー、OAuth のトークン、クライアントシークレット、Calyx が登録したクライアント ID はログインキーチェーンに保存されます。Remove はそのサーバーの項目を削除します。認可サーバーに登録したクライアント ID は、同じ発行者の次のサーバーで再利用できるよう残ります。
  • Send Message の画像は、一時ディレクトリの calyx-mcp-apps フォルダに書き出されます。

これらのサーバーが発生させる通信については、プライバシーポリシーを参照してください。