Fly.ioのMCPサーバー(flyctl mcp server)の使い方

Fly.ioの公式CLIであるflyctlには、fly mcp serverというサブコマンドとしてMCPサーバーが内蔵されています。別のパッケージをインストールする必要はなく、flyctlが入っていればそのまま使えます。アプリの作成からMachineの起動、証明書の管理、ログの取得まで、flyctlが持つコマンド群の多くをMCPツールとして呼び出せます。

flyctlが公開するコマンドカテゴリ

公式ドキュメントが挙げているのは次の9カテゴリですが、flyctlのソースコード(COMMANDS定義)を見ると、IPアドレス管理を担うipsカテゴリも実際には登録されており、ドキュメントの一覧からは漏れています。

公式ドキュメントは「ほとんどのサブコマンドに対応」と表現しており、flyctl本体のコマンド追加に追従してツール側も増えていく設計です。なおflyctlのソースコードでは、mcp serverを含むMCP関連コマンド一式が[experimental](実験的機能)と明記されています。ドキュメントページ自体にはこの注記が出てこないため、本番運用の前提にする場合はこの位置付けを踏まえておく必要があります。

実験的機能ではあるものの、開発自体は止まっていません。flyctlのリリース履歴では、MCP実装が依存するmark3labs/mcp-goのバージョンアップが数週間おきのリリースに含まれています。直近のv0.4.107では1.x系(1.1.0)に上がりました。設定ファイルまわりの修正も続いており、5月のv0.4.52でJSONコメント・末尾カンマの許容、9月のv0.4.101で書き出す設定ファイルのパーミッションの0600化が入っています。実験的ラベルは付いたままでも、放置されたコマンドではなく継続的にメンテナンスされている機能と見てよさそうです。

主なオプション早見表

fly mcp serverに渡せる主なフラグをまとめました。

Claude Codeに接続する

fly mcp serverはデフォルトで標準入出力(stdio)で動くサーバーです。Claude Codeへ接続するときは、コマンドをそのままstdioサーバーとして登録します。

claude mcp add --transport stdio fly -- fly mcp server

登録後は/mcpでサーバーがConnectedと表示されるか確認します。

ここで一つ、動き方を知っておくと権限の絞り方が変わります。公開されているflyctlのソースコードでは、MCPツールを呼ぶたびにflyctl自身が対応するサブコマンドを子プロセスとして実行し、その出力をテキストで返す作りになっています。トークンを渡したときだけ、子プロセスのコマンドに--access-tokenが付きます。何も渡さなければ、ログイン済みのflyctlが持つ個人トークンの権限で動きます。個人トークンは全組織・全アプリを操作できる範囲を持つため、権限を絞りたいなら次の節のトークンを明示的に渡します。

実行されたコマンドは標準エラー出力にExecuting flyctl command: ...の形で記録されます。secrets setの値だけはKEY=REDACTEDに伏せられ、それ以外のコマンドは引数がそのまま出るので、ログを共有するときは注意が要ります。

手順2の登録コマンドは、claude mcp add --helpが示す書式のとおり、環境変数の指定が-e、サーバー起動コマンドの前の区切りが--です。

claude mcp add fly -e FLY_ACCESS_TOKEN=<発行したトークン> -- fly mcp server

Claude Code v2.1.289のclaude mcp add --helpは、書式をclaude mcp add [options] <name> <commandOrUrl> [args...]と表示します。スコープの既定はlocal、トランスポートの既定はstdioです。-s projectを付けない限り、登録は現在のプロジェクトだけに効くローカル設定になります。

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のようなパスに依存しない値へ書き換えます。トークンは.mcp.jsonが対応している環境変数の展開(${VAR})で渡せば、リポジトリに値が残りません。

{
  "mcpServers": {
    "fly": {
      "command": "fly",
      "args": ["mcp", "server"],
      "env": {
        "FLY_ACCESS_TOKEN": "${FLY_ACCESS_TOKEN}"
      }
    }
  }
}

envは${VAR}の展開を受ける場所の一つで、各メンバーが自分のシェルでFLY_ACCESS_TOKENを設定しておけば、同じファイルが全員の環境で動きます。未設定のまま起動すると${FLY_ACCESS_TOKEN}という文字列がそのまま渡され、Claude Codeは/mcpに警告を出します。

自然文でアプリとMachineを操作する

接続できれば、各カテゴリのコマンドを自然文で呼び出せます。

my-appのステータスと、直近のリージョン配置を教えて

my-appのMachineを一覧して、止まっているものがあれば再起動して

my-appの証明書の有効期限を確認して

my-appにSECRET_KEYというシークレットを追加して

machineカテゴリはMachineの作成・起動・停止まで踏み込めるため、「試しに1台立てて動作確認する」のような操作もClaude経由で頼めます。一方でsecretsのように実運用に直結する操作も同じ枠組みで呼べてしまうため、どのツールがどこまで書き込み可能かは、後述するトークンのスコープと合わせて把握しておく必要があります。orgsやplatformのような読み取り中心のカテゴリと、machineやsecretsのような書き込みを伴うカテゴリが同じ/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つを満たせば動きますが、複数指定した場合はヘッダーが最優先されるため、共有サーバーで一時的に別のトークンを使いたいときはヘッダー経由の指定が便利です。

1. リクエストのAuthorizationヘッダーに載せるBearer <token>
2. fly mcp server起動時の--access-tokenフラグ
3. 環境変数FLY_ACCESS_TOKEN

ここで使うトークンはfly auth tokenでは取得しません。MCP経由での操作は自動化の一種なので、fly tokens create系のコマンドで別途発行します。個人トークンとの違いは次の比較のとおりです。

読み取り専用の組織トークン(fly tokens create readonly)は、これをさらに「組織とその資源を読むだけ」に絞ったものです。アプリ単位のfly tokens create deployは、1つのアプリだけを対象にするトークンです。

fly tokens create org --name "claude-mcp" --expiry 720h

トークンの既定の有効期限は20年と非常に長いです。公式のトークンのページは、用途に必要な最短の期間を指定し、時間の面でも範囲の面でもアクセスを絞るよう求めています。MCPサーバーに渡すトークンは、Claudeに任せる操作の範囲(アプリ作成・シークレット変更・Machine操作まで含むか)に応じて--expiryを短く切り、用途が終わったらfly tokens revokeで失効させる運用が安全です。

リモートで動かす場合の注意

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から接続できます。まずは個人のローカル環境で、読み取り専用トークンと短い有効期限から試すのが無難です。appsの作成やsecretsの変更など書き込みが要る段階になってから、トークンの種類を切り替えます。

実験的機能である以上、flyctlをアップデートするたびに/mcpでサーバーがConnectedのままかを確かめておくと、挙動の変化に早めに気づけます。

MCPサーバーの追加構文やスコープの使い分けはClaude Code MCP設定ガイドにまとめています。他のPaaSとの比較はRailwayのMCPサーバー、本番デプロイ権限の絞り方はPaaS系MCPの本番デプロイ権限で扱っています。