Fly.ioのMCPサーバー(flyctl mcp server)の使い方
flyctlには追加インストール不要の公式MCPサーバーが内蔵されています。Machines・証明書・ログ操作までの手順と、Claude Code接続時に迷いやすいトークンと設定先の選び方をまとめます。
Fly.ioの公式CLIであるflyctlには、fly mcp serverというサブコマンドとしてMCPサーバーが内蔵されています。別のパッケージをインストールする必要はなく、flyctlが入っていればそのまま使えます。アプリの作成からMachineの起動、証明書の管理、ログの取得まで、flyctlが持つコマンド群をひとしきりMCPツールとして呼び出せる構成です。
flyctlが公開するコマンドカテゴリ
公式ドキュメントが挙げているのは次の9カテゴリですが、flyctlのソースコード(COMMANDS定義)を見ると、IPアドレス管理を担うipsカテゴリも実際には登録されており、ドキュメントの一覧からは漏れています。
| カテゴリ | 内容 |
|---|---|
apps | 内容Fly Machineの集合であるFlyアプリの作成・管理 |
certs | 内容デプロイ済みアプリのTLS証明書管理 |
logs | 内容稼働中インスタンスのログ取得 |
machine | 内容軽量VM(Fly Machines)の起動・停止・作成 |
orgs | 内容組織とユーザーアクセスの管理 |
platform | 内容プラットフォーム自体の情報取得 |
secrets | 内容アプリ実行時の環境変数(シークレット)の設定 |
status | 内容デプロイ状況・リージョン配置の確認 |
volumes | 内容Fly Machines向け永続ストレージの管理 |
ips | 内容割り当て済みIPアドレスの一覧・管理(公式ドキュメントの一覧には未掲載) |
公式ドキュメントは「ほとんどのサブコマンドに対応」と表現しており、flyctl本体のコマンド追加に追従してツール側も増えていく設計です。なおflyctlのソースコードでは、mcp serverを含むMCP関連コマンド一式が[experimental](実験的機能)と明記されています。ドキュメントページ自体にはこの注記が出てこないため、本番運用の前提にする場合はこの位置付けを踏まえておく必要があります。
実験的機能ではあるものの、開発自体は止まっていません。flyctlのリリース履歴を見ると、MCP実装が依存するmark3labs/mcp-goライブラリのバージョンアップがほぼ毎回のリリースに含まれており、直近ではJSONコメント・末尾カンマを許容する設定ファイルパーサーの修正や、書き出す設定ファイルのパーミッションを0600に絞る修正も入っています。実験的ラベルは付いたままでも、放置されたコマンドではなく継続的にメンテナンスされている機能と見てよさそうです。
主なオプション早見表
fly mcp serverに渡せる主なフラグをまとめました。
| フラグ | 用途 |
|---|---|
--claude / --cursor / --vscode / --neovim / --windsurf / --zed | 用途対応クライアントの設定ファイルへ自動書き込み |
--config <path> | 用途任意の設定ファイルパスを直接指定 |
-i / --inspector | 用途MCP Inspectorを起動して動作確認 |
--sse / --stream | 用途リモート接続用のトランスポートを有効化 |
--bind-addr | 用途バインドアドレスの変更(既定は127.0.0.1) |
--access-token | 用途認証トークンを直接指定 |
--port | 用途サーバーのポート指定(既定は8080) |
Claude Codeに接続する
fly mcp serverはデフォルトで標準入出力(stdio)で動くサーバーです。Claude Codeへ接続するときは、コマンドをそのままstdioサーバーとして登録します。
claude mcp add --transport stdio fly -- fly mcp server登録後は/mcpでサーバーがConnectedと表示されるか確認します。API呼び出しに使うトークンは、flyctlが既にログイン済みであればそのセッションの認証情報がそのまま使われます。
fly mcp serverは--configフラグに任意のファイルパスを渡すと、Claude Codeのプロジェクトスコープ設定と同じmcpServersキーの形式でその場所に設定を書き込めます。
fly mcp server --config .mcp.jsonただしこの--configはチーム共有向けではありません。flyctlのソースコードでは、生成した設定ファイルのcommandに、実行したマシン上のflyctlの絶対パス(os.Executable()で取得した値)がそのまま書き込まれる実装になっています。インストール場所やOSが違うメンバーの環境ではそのパスが存在せず起動できませんし、生成者のホームディレクトリのパスがリポジトリに残ってしまいます。.mcp.jsonをそのままコミットして共有するのは避け、各自が自分の環境で--configを実行するか、後述するようにclaude mcp addを個別に打つ運用にします。どうしてもファイルを共有したい場合は、生成後にcommandをflyのようなパスに依存しない値へ手で書き換えてからコミットしてください。
自然文でアプリとMachineを操作する
接続できれば、各カテゴリのコマンドを自然文で呼び出せます。
my-appのステータスと、直近のリージョン配置を教えてmy-appのMachineを一覧して、止まっているものがあれば再起動してmy-appの証明書の有効期限を確認してmy-appにSECRET_KEYというシークレットを追加してmachineカテゴリはMachineの作成・起動・停止まで踏み込めるため、「試しに1台立てて動作確認する」のような操作もClaude経由で頼めます。一方でsecretsのように実運用に直結する操作も同じ枠組みで呼べてしまうため、どのツールがどこまで書き込み可能かは、後述するトークンのスコープと合わせて把握しておく必要があります。orgsやplatformのような読み取り中心のカテゴリと、machineやsecretsのような書き込みを伴うカテゴリが同じ/mcp接続の中に同居している点は、他のクラウド系MCPサーバーと共通する設計です。会話の中で「これは確認だけ」「これは実行してよい」を明示的に伝える習慣があると、意図しない操作を防ぎやすくなります。
MCP Inspectorで動作を確認する
登録する前に、どんなツールが呼び出せるかを確認したい場合はMCP Inspectorを使います。Node.jsのインストールが前提です。
fly mcp server -i起動後にhttp://127.0.0.1:6274を開き、Connect→List Toolsの順に進むと、fly-platform-statusやfly-apps-list、fly-machines-listのようなツール一覧が確認できます。任意のツールを選んでフォームに値を入れ、Run toolを押せば実際の呼び出し結果をブラウザ上で確認できます。実運用の前にどのツールがどんな入力を要求するかを把握しておくと、Claude側に自然文で頼むときの解像度が上がります。ツール名がfly-<カテゴリ>-<操作>という規則的な命名になっている点も、Inspector上で一覧を眺めるとすぐに気づけます。
使うトークンは用途に合わせて絞る
MCP経由でFly.ioを操作する認証トークンは、優先順位付きで3つの取得元が用意されています。どれか1つを満たせば動きますが、複数指定した場合はヘッダーが最優先されるため、共有サーバーで一時的に別のトークンを使いたいときはヘッダー経由の指定が便利です。
- リクエストの
Authorizationヘッダーに載せるBearer <token> fly mcp server起動時の--access-tokenフラグ- 環境変数
FLY_ACCESS_TOKEN
ここで使うトークンはfly auth tokenでは取得しません。このコマンドが返すのは有効期限の短い個人トークンで、公式ドキュメントも自動化用途には向かないと明記しています。MCP経由での操作は自動化の一種なので、fly tokens create系のコマンドで組織スコープのトークンを別途発行します。
fly tokens create org --name "claude-mcp" --expiry 720hトークンの既定の有効期限は20年と非常に長いです。MCPサーバーに渡すトークンは、Claudeに任せる操作の範囲(アプリ作成・シークレット変更・Machine操作まで含むか)に応じて--expiryを短く切り、用途が終わったらfly tokens revokeで失効させる運用が安全です。読み取りだけで十分ならfly tokens create readonlyで発行したトークンに絞る選択肢もあり、Claudeにステータス確認やログ閲覧だけを任せたい段階ではこちらから試すのが安全です。
リモートで動かす場合の注意
fly mcp serverは既定で127.0.0.1にバインドされ、同一マシンからのアクセスしか受け付けません。--sseまたは--streamを指定するとネットワーク越しの接続に対応しますが、公式ドキュメントは「このサーバーをリモートで動かすと、他人が自分の代わりにコマンドを実行できてしまう可能性がある」と明確に警告しています。--bind-addrでバインドアドレスを変更する前に、認証トークンとネットワーク経路の両方を絞り込んでおく必要があります。
チーム開発でMCPサーバーを1箇所にまとめて置きたいという動機は理解できますが、fly mcp serverはもともとローカルの個人利用を前提に設計されています。複数人で共有したい場合でも、サーバー自体を1台のマシンに集約するのではなく、各自のローカル環境でclaude mcp addする構成のほうが、この警告に沿った安全な使い方になります。
よくあるつまずき
--claudeを実行したのにClaude Codeで認識されない: 前述の通りClaude Desktop向けの設定ファイルが更新されるだけです。Claude Code CLIにはclaude mcp addか--config .mcp.jsonで別途登録します--configで書き出した.mcp.jsonをClaude Codeが読んでくれない: プロジェクトスコープの.mcp.jsonはセキュリティ上、Claude Codeを一度対話的に起動して承認ダイアログを通すまで有効になりません。claudeをそのディレクトリで起動し、サーバーの承認を済ませますfly auth tokenのトークンをMCPサーバーに渡してすぐ切れる: このコマンドは短命な個人トークン用です。継続的に使うならfly tokens create orgなどで発行し直します- MCP Inspectorが起動しない: InspectorはNode.jsアプリケーションとして動くため、Node.js未インストール環境では動きません。先にNode.jsを入れてから
fly mcp server -iを実行します - リモートホストしたらアクセスできないと言われる: 既定のバインドアドレスは
127.0.0.1なので、別マシンからのアクセスには--bind-addrの指定が要ります。ただし変更前にセキュリティ上のリスクを理解しておく必要があります - ツールを呼んだが権限エラーになる: 読み取り専用トークンでは
appsの作成やsecretsの変更はできません。操作の内容に応じたスコープのトークンを使っているか確認します
まとめ
flyctlにはFly.io公式のMCPサーバーが内蔵されており、追加のパッケージインストールなしでclaude mcp add --transport stdio fly -- fly mcp serverだけでClaude Codeから接続できます。ただし--claudeの自動設定フラグはClaude Desktop専用で、Claude Code CLIには効きません。認証トークンはfly auth tokenではなく用途に応じたスコープのfly tokens create系コマンドで発行し、有効期限を絞って運用するのが安全です。まだ[experimental]の位置付けであることも踏まえ、本番のデプロイ操作をすべて任せる前に、まずはstatusやlogsのような読み取り系のツールから試すのが無難です。
チームで使う場合も、--configで生成した.mcp.jsonをそのままコミットして配るのは避けます。commandに生成者のマシン固有のflyctl絶対パスが書き込まれるため、他のメンバーの環境では起動できません。各自のローカルでclaude mcp addするか、共有するならcommandをパスに依存しない形へ手で書き換えてからコミットしてください。実験的機能である以上、flyctlをアップデートするたびに/mcpでサーバーが引き続きConnectedのままかを確認しておくと、挙動の変化に早めに気づけます。
MCPサーバーの追加構文やスコープの使い分けはClaude Code MCP設定ガイドにまとめています。他のPaaSとの比較はRailwayのMCPサーバー、本番デプロイ権限の絞り方はPaaS系MCPの本番デプロイ権限で扱っています。