Docker MCP Gateway セットアップ完全ガイド：Profile・クライアント接続・シークレット

Docker MCP Gateway は、各 MCP サーバーを隔離された Docker コンテナとして実行し、それらすべてを単一の MCP エンドポイントから AI クライアントへ公開するオープンソースのプロキシです。サーバーを Profile に追加し、docker mcp gateway run --profile <name> でゲートウェイを起動して、Claude Code・Cursor・VS Code などの MCP クライアントをその 1 つのゲートウェイに向けるだけ。サーバーごとに個別設定する必要はありません。

このガイドでは、現行の（Profile ベースの）ワークフローを最初から最後まで扱います：インストール、Catalog、Profile、クライアント接続、シークレット、デフォルトで有効なセキュリティ機能、そして Docker Compose によるヘッドレス運用です。以下のコマンドはすべて Docker 公式の MCP Toolkit ドキュメント と docker/mcp-gateway の README（2026 年 10 月時点）で確認しています。

MCP Toolkit・MCP Gateway・MCP Catalog の違い

この 3 つの名前は 1 つのスタックを指しています：

アーキテクチャはシンプルです：AI クライアント → MCP Gateway → MCP サーバー（コンテナ）。クライアントはゲートウェイとしか通信しないため、サーバーを一度設定すれば、接続中のすべてのクライアントから利用できます。

前提条件

• Docker Desktop 4.62 以降。 Docker の CLI リファレンス には、現行の docker mcp コマンドには 4.62 以上が必要と明記されています。それより古いバージョンでは Toolkit の UI が異なります。プラグインは Docker Desktop に同梱されているので、docker mcp --help はすでに動くはずです。
• Desktop ではなく Docker CE・WSL2・コンテナ環境の場合は？ CLI はそのまま使えます。デーモンが動いているのに "Docker Desktop is not running" と出る場合は DOCKER_MCP_IN_CONTAINER=1 を設定し、Profile 機能を明示的に有効化します：

export DOCKER_MCP_IN_CONTAINER=1
docker mcp feature enable profiles
docker mcp feature list

ステップ 1：Catalog を見る

デフォルトの Catalog は mcp/docker-mcp-catalog です。pull して、含まれるサーバーを一覧表示します：

docker mcp catalog pull mcp/docker-mcp-catalog
docker mcp catalog ls
docker mcp catalog server ls mcp/docker-mcp-catalog

Docker Desktop では同じリストが MCP Toolkit → Catalog にあります。各エントリには github-official、duckduckgo、playwright のようなサーバー名があり、次のステップで catalog://mcp/docker-mcp-catalog/<server> の形で参照します。

ステップ 2：Profile を作成する

Profile とは、名前付きのサーバーの集合（各サーバーの設定とツールの許可リストを含む）で、クライアントはこれに接続します。Profile は旧来のグローバルな「有効化済みサーバー」リストに代わるもので、以前の Toolkit の設定は default という名前の Profile に自動で移行されます。

# Create a profile with two catalog servers
docker mcp profile create --name dev-tools \
  --server catalog://mcp/docker-mcp-catalog/github-official+duckduckgo

# Add another server later
docker mcp profile server add dev-tools \
  --server catalog://mcp/docker-mcp-catalog/playwright

# Inspect what you have
docker mcp profile list
docker mcp profile show dev-tools
docker mcp profile server ls --filter profile=dev-tools

サーバー参照は Catalog に限りません。1 つの Profile に catalog:// エントリ、自作イメージ（docker://my-server:latest）、ローカル定義（file://./my-server.yaml）、MCP Registry の URL（https://registry.modelcontextprotocol.io/v0/servers/<id>）を混在させられます。ただしリポジトリの Profile ドキュメント には Registry 参照はまだ完全には実装されていないとあるため、現時点では Catalog かイメージ参照を優先しましょう。

初日から使うべき Profile の機能が 2 つあります：

# Per-server configuration (keys differ per server)
docker mcp profile config dev-tools --set github-official.<key>=<value>
docker mcp profile config dev-tools --get-all

# Tool allowlists: expose only what the agent needs
docker mcp profile tools dev-tools --disable-all github-official
docker mcp profile tools dev-tools --enable github-official.list_issues

ツールを絞ることは見た目以上に重要です。公開したツールはすべてコンテキストのトークンを消費し、ツールが少ないほど誤ったツール選択も減ります（MCP のツールディスカバリー のガイドも参照）。

UI を使う場合は MCP Toolkit → Profiles → Create profile を選び、Catalog タブで Profile のドロップダウンからサーバーを追加します。Profile の Tools タブでは個々のツールをオン／オフできます。

ステップ 3：ゲートウェイを起動する

# stdio, using the "default" profile
docker mcp gateway run

# stdio, a specific profile
docker mcp gateway run --profile dev-tools

# Debug: show config, images and servers, then exit without listening
docker mcp gateway run --profile dev-tools --verbose --dry-run

--profile を指定しない場合、ゲートウェイは default という Profile を使い、それが存在しなければ空の設定で起動します。多くの場合、stdio モードのゲートウェイを自分で起動する必要はありません。MCP クライアントが他の stdio サーバーと同じように docker mcp gateway run をサブプロセスとして起動します。

ステップ 4：クライアントを接続する

最も手早いのは docker mcp client connect で、クライアントに合った設定ファイルを書き込んでくれます。対応クライアント名（自動生成された CLI リファレンス より）には claude-code、claude-desktop、cursor、vscode、codex、gemini、zed、cline、continue、goose、kiro、lmstudio、opencode などがあります。

docker mcp client ls
docker mcp client connect <client> --profile dev-tools
docker mcp client disconnect <client>

Claude Code

docker mcp client connect claude-code --profile dev-tools --global

標準の claude mcp add 構文で手動追加することもできます（-- 以降がサーバーのコマンドです）：

claude mcp add --scope user MCP_DOCKER -- docker mcp gateway run --profile dev-tools

Claude Code 内で /mcp を実行し、ゲートウェイが接続されたことを確認します。CLAUDE_CONFIG_DIR を設定している場合、client connect は ~/.claude.json ではなくそのディレクトリの .claude.json に書き込みます。Claude Code の設定については Claude Code MCP ガイド で詳しく解説しています。

Cursor

docker mcp client connect cursor --profile dev-tools

手動で設定する場合は ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に書きます：

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "dev-tools"]
    }
  }
}

VS Code（GitHub Copilot）

プロジェクトフォルダ内で実行します。.vscode/mcp.json が作成されますが、これはユーザー固有のファイルなので git には含めないでください：

docker mcp client connect vscode --profile dev-tools
echo ".vscode/mcp.json" >> .gitignore

手動設定では VS Code の servers キーを使います：

{
  "servers": {
    "MCP_DOCKER": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "dev-tools"]
    }
  }
}

Claude Desktop はワンクリックです：MCP Toolkit → Clients で Claude Desktop の横にある Connect を選び、再起動します。その他のクライアントは MCP クライアント一覧 を参照してください。

ステップ 5：シークレットと OAuth

API キーが必要なサーバーは、クライアント設定の環境変数ではなくゲートウェイからキーを受け取ります。デフォルトでは、ゲートウェイは OS のキーチェーンを基盤とする Docker Desktop のシークレットストア（--secrets=docker-desktop）から読み込みます。

# Pipe the value in via stdin so it never lands in shell history
echo "$GITHUB_TOKEN" | docker mcp secret set github.personal_access_token
docker mcp secret ls
docker mcp secret rm github.personal_access_token

シークレット名はサーバーごとに異なります（Docker Desktop でそのサーバーの Configuration タブを見るか、docker mcp catalog server inspect で確認）。シークレットはそれを宣言したサーバーにだけスコープされるため、あるサーバーが別のサーバーのキーを読むことはできません。

OAuth ベースのサーバーは、Docker Desktop でサーバーの Configuration タブを開き、OAuth を選んでブラウザでの認可を完了します。後から OAuth タブでアクセスを取り消せます。CLI 版は docker mcp oauth --help にあります。Docker の Profile ドキュメント には注意点が 2 つあります：OAuth 認証情報はすべての Profile で共有されること、そしてレジストリに push した Profile には認証情報が含まれないため、チームメンバーは各自のマシンで認可し直す必要があることです。プロトコル側の仕組みは MCP の認証と OAuth を読んでください。

ゲートウェイがデフォルトで提供するセキュリティ

npx some-server を直接実行する代わりにゲートウェイの背後にサーバーを置く最大の理由がこれです。リポジトリの セキュリティモデル によると：

ホストのディレクトリマウントはデフォルトで読み取り専用で、許可リストにあるパスに限られます。リモートの MCP URL は公開 HTTPS である必要があります。ただし、これらはツールが返すコンテンツ内のプロンプトインジェクションは防げないので、MCP セキュリティのベストプラクティス の習慣と組み合わせてください。

HTTP で複数のクライアントに提供する

stdio では各クライアントが専用のゲートウェイプロセスを持ちます。1 つのゲートウェイを共有するには Streamable HTTP トランスポートに切り替えます：

export MCP_GATEWAY_AUTH_TOKEN="$(openssl rand -hex 32)"
docker mcp gateway run --profile dev-tools --transport streaming --port 8080

クライアントは http://localhost:8080/mcp に接続し、Authorization: Bearer <token> ヘッダーを送る必要があります。Claude Code の場合：

claude mcp add --transport http docker-gateway http://localhost:8080/mcp \
  --header "Authorization: Bearer $MCP_GATEWAY_AUTH_TOKEN"

ブラウザからのリクエストは localhost の Origin からのみ受け付けられ、/health はヘルスチェック用に認証不要です。

Docker Compose でゲートウェイを動かす

ゲートウェイは docker/mcp-gateway イメージとしても公開されているため、エージェントや CI から Docker Desktop なしで使えます。サーバーコンテナを起動するために Docker ソケットが必要です。このモードでは Profile の代わりに --servers（Catalog 名）でサーバーを列挙し、シークレットはファイルから渡せます：

services:
  gateway:
    image: docker/mcp-gateway
    command:
      - --transport=streaming
      - --port=8811
      - --servers=github-official,duckduckgo
      - --secrets=docker-desktop:/run/secrets/mcp_secret
    environment:
      - MCP_GATEWAY_AUTH_TOKEN=${MCP_GATEWAY_AUTH_TOKEN}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    secrets:
      - mcp_secret

secrets:
  mcp_secret:
    file: .env

.env には github.personal_access_token=... のような行を書きます。エージェント側のサービスは http://gateway:8811/mcp に接続します。リポジトリの examples フォルダ には Python クライアント、PostgreSQL、インターセプター、ヘルスチェック、リモートサーバーなどのバリエーションがあります。--secrets はコロン区切りの検索チェーンを受け取り、まず Docker Desktop、次にマウントされたファイルを参照します。

Dynamic MCP：エージェント自身にサーバーを追加させる

Toolkit が有効な場合、ゲートウェイは mcp-find（Catalog を検索）、mcp-add と mcp-remove（現在のセッションにサーバーを追加・削除）、mcp-config-set といった管理用ツールも公開します。この方法で追加したサーバーは現在のセッション内でのみ有効で、Profile には保存されません。Docker はこの機能を実験的と位置付けています。固定のツールリストにしたい場合は docker mcp feature disable dynamic-tools で無効化できます（ドキュメント）。

トラブルシューティング

• クライアントにツールが表示されない。 docker mcp gateway run --profile dev-tools --verbose --dry-run を実行します。有効なサーバー、pull されたイメージ、読み込まれたツール数が表示されるので、タイプミスやシークレット・イメージの不足が見つかります。
• 特定のツール呼び出しだけを切り分けたい。 docker mcp tools ls の後に docker mcp tools call <tool> key=value を実行します。--verbose を付けるとゲートウェイ内部の動きが見えます。
• Linux／WSL2 で "Docker Desktop is not running" と出る。 DOCKER_MCP_IN_CONTAINER=1 を export します。
• "unsupported dialect" のスキーマエラー。 ゲートウェイを更新してください。現行バージョンは draft-07 のツールスキーマを JSON Schema 2020-12 に自動変換します。
• 参考にしたチュートリアルが docker mcp server enable を使っている。 それは Profile 導入前のワークフローです。4.62 以降では docker mcp profile server add でサーバーを Profile に追加してください。
• HTTP トランスポートで 401 が返る。 MCP_GATEWAY_AUTH_TOKEN の Bearer トークンを送ってください。クライアントの外でエンドポイントを試すには MCP Inspector が便利です。

次のステップ

まずは信頼できるサーバー 2〜3 個だけの小さな Profile を作り、各サーバーを実際に呼び出すツールだけに絞って、クライアントを 1 つだけ接続しましょう。最初の候補としては GitHub MCP Server、ブラウザ自動化の Playwright MCP（Playwright セットアップガイド も参照）、最新ドキュメントを提供する Context7 がおすすめです。さらに広げたくなったら、MCP.so のサーバーディレクトリ で自分のスタックに合うサーバーを探してください。