MCPサーバーのDockerfile完全ガイド:Node.js・Python用テンプレートと実測した7つの落とし穴【MCP Hosting 2026】
Node.js/TypeScript・Python・GitHubのMCPサーバー向けDockerfileを、stdio用とStreamable HTTP用の両方で紹介。npx・uvxのコールドスタート、npm startによるstdout汚染、PID 1のSIGTERM無視、-i、ヘルスチェック、秘密情報の扱いを実測で解説します。
最終更新:2026年11月5日 / 対象:MCP仕様 2026-07-28(stdio・Streamable HTTP)、MCP TypeScript SDK 1.32.2、MCP Python SDK 2.3.0、
@modelcontextprotocol/server-filesystem2.2.0、mcp-server-time2026.11.4、npm 10.9.9、Node.js 22.23.4、Python 3.13.18。検証は2026年11月5日に実施しました(方法は2章)。
結論(30秒で読める要約)
MCPサーバーのDockerfileは、普通のコンテナ定義に「MCPならではのルール」を3つ足したものです。stdoutにはJSON-RPC以外を出さない、起動時に何もダウンロードしない、停止の合図(SIGTERM)できちんと終わる、の3つです。MCP Hostingでは、同じイメージを手元のstdioサーバー(docker run -i)としても、URLで公開するStreamable HTTPサーバーとしても使えます。
実際に測ってわかったこと:
npx/uvxで起動するより、ビルド時にインストールする方が速い。キャッシュが空の状態だと、npx -yは最初のツール一覧が返るまで2.2〜2.4秒かかりました。nodeで直接起動すると0.20〜0.25秒です。キャッシュが空のuvxは12.5秒と18.5秒で、1回はクライアントの60秒タイムアウトを超えました。npm startはstdioのルールを破る。npmはサーバーの最初のメッセージより前に、バナー2行と空行2行をstdoutへ出しました。TypeScript SDKのクライアントはJSONのパースエラーを4件記録しました。npm start --silentやnode dist/server.jsなら何も出ません。- PID 1で動くNode.jsは
SIGTERMを無視する。シグナルハンドラーのないNodeのHTTPサーバーは、SIGTERMを送って5秒たっても動いていました。これではdocker stopが既定の10秒待ったあと強制終了します。ハンドラーを入れると0.11秒、uvicornで動くPython SDKのサーバーは0.21秒で終了しました。 -iなしのstdioコンテナはすぐ終わる。stdinが閉じているとサーバーはEOFを受け取り、0.15秒・終了コード0で終了しました。- マルチステージビルドで依存パッケージが63MBから26MBに減った。TypeScriptのビルド用ツールをビルド段階に置いていけるからです。
コピーして使えるDockerfileは、4章(Node.js/TypeScript)、5章(Python)、6章(GitHubで見つけたサーバー)にあります。
目次
- MCPサーバーのDockerfileがやるべきこと
- 検証の方法
- stdio用イメージとHTTP用イメージ
- Node.js/TypeScriptのMCPサーバー用Dockerfile
- PythonのMCPサーバー用Dockerfile
- GitHubで見つけたMCPサーバー用Dockerfile
- 実測した7つの落とし穴
- コンテナをClaude・Cursor・エージェントにつなぐ
- Docker MCP Toolkit、自前のDockerfile、ホスティングのどれを選ぶか
- チェックリスト
- トラブルシューティング(症状→原因→対処)
- NodeFlareならこう解決できる
- よくある質問
1. MCPサーバーのDockerfileがやるべきこと
MCPサーバーのDockerfileとは、ネットワークからのダウンロードなしでMCPサーバーを1つ起動し、stdoutにはプロトコルのメッセージだけを書き、root以外のユーザーで動いて SIGTERM で止まるイメージを作るためのものです。それ以外は普通のコンテナの作法と同じです。
MCP特有の部分は、トランスポートの決まりから来ています。仕様はstdioについて「サーバーは、有効なMCPメッセージでないものをstdoutに書いてはならない(MUST NOT)」とし、ログは「stderrにUTF-8の文字列を書いてよい(MAY)」としています。メッセージは改行区切りのJSON-RPCです。コンテナの中ではランチャーやラッパーもstdoutに書けるので、このルールを破りやすくなります。
| 要件 | MCPで大事な理由 | Dockerfileのどこに書くか |
|---|---|---|
| stdoutはJSON-RPCだけ | stdioクライアントはstdoutの各行をメッセージとして読む | npm start ではなく ENTRYPOINT ["node", "dist/server.js"] |
| 起動時にダウンロードしない | コールドスタートのたびに繰り返される(7.1) | ビルド時に RUN npm ci/RUN pip install |
| バージョンを固定する | リリースごとにツールが変わることがある | ロックファイル、== での固定、イメージのタグ |
SIGTERM で止まる |
docker stop もホスティング先も最初に送る |
--init、シグナルハンドラー、exec形式の CMD |
| root以外で動かす | ツールが乗っ取られたときの被害を減らす | USER node や独自のUID |
HTTPなら 0.0.0.0 で待ち受け、$PORT を読む |
ループバックはコンテナの外から届かない | サーバーのフラグや環境変数 |
| 秘密情報をイメージに入れない | ビルド引数や ENV はイメージのレイヤーに残る |
実行時の -e、シークレットマウント |
他人のサーバーのDockerfileを書く前に、そもそもコンテナで動くかを MCP Hostingの事前チェック で確かめてください。デスクトップアプリを操作するサーバーは、コンテナにしても役に立ちません。
2. 検証の方法
検証用の環境ではベースイメージを取得できませんでした(Docker Hubへの通信が外向き通信のポリシーで遮断されていました)。そのため、この記事のDockerfileそのものはビルドしていません。代わりに、Dockerfileの中で実行するコマンドをすべてホスト上で実行し、コンテナで問題になる条件を再現しました。
| コンテナでの条件 | 再現の方法 |
|---|---|
| パッケージのキャッシュが空のコールドスタート | 毎回新しい npm_config_cache/UV_CACHE_DIR を使う |
| PID 1で動くプロセス | unshare --pid --fork --mount-proc(カーネルはPID 1に同じシグナルのルールを適用する) |
-i なしの docker run |
stdinを /dev/null からつなぐ |
| stdioクライアント | MCP TypeScript SDK 1.32.2の StdioClientTransport と、Python SDK 2.3.0の stdio_client |
| HTTPのヘルスチェック | Python SDK 2.3.0のサーバーに server/discover をPOSTする |
時間の計測はそれぞれ3回行いました。ダウンロードの時間は検証環境のプロキシに左右されるので、ベンチマークではなく一例として見てください。
3. stdio用イメージとHTTP用イメージ
同じサーバーのコードを2通りの形でイメージにでき、Dockerfileの違いはほぼ最後の数行だけです。
| stdio用イメージ | HTTP用イメージ | |
|---|---|---|
| 誰が起動するか | MCPクライアントが docker run -i --rm で起動 |
自分かホスティング先が1回起動 |
| トランスポート | stdin/stdout | ポート上のStreamable HTTP(通常 /mcp) |
| どこから使えるか | クライアントが動くマシンだけ | URLを知っているどのクライアントからも |
EXPOSE/HEALTHCHECK |
不要 | 必要 |
| 寿命 | クライアントのセッションごとに1コンテナ | 長時間動き、複数のクライアントで共有 |
| 主な使い道 | 手元のPCでサーバーを隔離する | Web版Claude、別マシンのCursor、クラウドのエージェント |
stdioしか話さないサーバーをHTTP用イメージにしたい場合は、イメージの中にブリッジを入れるか、stdioを包んでくれるホスティングを使います。ブリッジごとの増えるメモリ量は MCP Hostingのメモリ見積もり で実測しています。
4. Node.js/TypeScriptのMCPサーバー用Dockerfile
2段階のビルドにします。1段目ですべての依存パッケージを入れてコンパイルし、2段目にはコンパイル済みのコードと本番用の依存パッケージだけをコピーします。検証用プロジェクト(MCP TypeScript SDK 1.32.2とzod、開発用にTypeScript・@types/node・tsx)では、node_modules は npm ci 直後に63MB、npm prune --omit=dev のあとに26MBでした。削ったあとのサーバーも tools/list に正しく応答しました。
# syntax=docker/dockerfile:1
FROM node:24-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev
FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build --chown=node:node /app/package.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
# exec形式:nodeが直接シグナルを受け取り、npmがstdoutに何も出さない
ENTRYPOINT ["node", "dist/server.js"]
HTTP用イメージにするなら、USER node のあとにポートとヘルスチェックを足します。
ENV PORT=8080
EXPOSE 8080
COPY --chown=node:node healthcheck.mjs ./
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD ["node", "healthcheck.mjs"]
サーバー側は 0.0.0.0 で待ち受けて process.env.PORT を読み、SIGTERM を処理する必要があります(7.4)。処理しない場合は --init 付きでコンテナを起動します。.dockerignore には少なくとも node_modules、dist、.git、.env を書き、手元のビルド結果や秘密情報がイメージに入らないようにします。
healthcheck.mjs は、2026-07-28版のサーバーなら必ず答える server/discover を送ります。slim系のイメージにはcurlが入っていないので、Node.js組み込みの fetch を使っています。Python SDK 2.3.0のサーバーに対して、動いている間は終了コード0、止めたあとは1を返しました。
// healthcheck.mjs - MCPエンドポイントが server/discover に200を返せば終了コード0
const port = process.env.PORT || 8080;
const meta = {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { name: "healthcheck", version: "1" },
"io.modelcontextprotocol/clientCapabilities": {},
};
const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"MCP-Protocol-Version": "2026-07-28",
"Mcp-Method": "server/discover",
},
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "server/discover", params: { _meta: meta } }),
signal: AbortSignal.timeout(3000),
}).catch(() => null);
process.exit(res && res.status === 200 ? 0 : 1);
セッション方式の旧SDK(プロトコル2025-11-25以前)を使っているサーバーには server/discover がないので、代わりに initialize を送って確かめてください。
5. PythonのMCPサーバー用Dockerfile
コンパイルが必要な依存パッケージがなければ、PythonのMCPサーバーにビルド段階は要りません。バージョンを固定した依存パッケージを入れ、root以外のユーザーを作り、スクリプトを python で直接起動します。mcp 2.3.0だけを入れた仮想環境は39MBで、一番大きいパッケージは15MBの cryptography でした。
# syntax=docker/dockerfile:1
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt # 例:mcp==2.3.0
COPY server.py ./
RUN useradd --uid 10001 --no-create-home app
USER app
ENTRYPOINT ["python", "server.py"]
PYTHONUNBUFFERED=1 はstderrのログをすぐ docker logs に出すための設定です。うっかり書いた print() が安全になるわけではありません(7.3)。
HTTP用イメージでは、ホストとポートを明示します。Python SDK 2.3.0の既定値は host="127.0.0.1"、port=8000 で、そのままではコンテナの外から届きません。
import os
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("demo")
@mcp.tool()
def echo(text: str) -> str:
return text
if __name__ == "__main__":
mcp.run(transport="streamable-http", host="0.0.0.0",
port=int(os.environ.get("PORT", "8000")), json_response=True)
PORT=8123 で起動したこのサーバーは、Host: mcp.example.com を付けた server/discover のPOSTに200を返しました。ただし host="0.0.0.0" にするとSDKのHostとOriginのチェックも緩くなります。前段にそれらを検証するプロキシを置くか、transport_security を自分で設定してください。そのうえで4章と同じ EXPOSE、ENV PORT、HEALTHCHECK を足します。python:3.13-slim にはNode.jsがないので、ヘルスチェックはPythonで書くかcurlを入れます。
uvicornは SIGTERM を自分で処理します。PID 1として動かしたPython SDKのサーバーは「Shutting down」とログを出し、0.21秒・終了コード0で終わりました。
6. GitHubで見つけたMCPサーバー用Dockerfile
公開されている他人のサーバーは、ビルド時に正確なバージョンを入れて、そのコマンドを直接起動します。READMEにある npx -y や uvx の行を、そのまま CMD に写さないでください。
# npmで公開されているNode.jsのサーバー
FROM node:24-slim
RUN npm install -g @modelcontextprotocol/server-filesystem@2.2.0
USER node
ENTRYPOINT ["mcp-server-filesystem", "/data"]
# PyPIで公開されているPythonのサーバー
FROM python:3.13-slim
RUN pip install --no-cache-dir mcp-server-time==2026.11.4
RUN useradd --uid 10001 --no-create-home app
USER app
ENTRYPOINT ["mcp-server-time"]
ベースイメージを選ぶ前に engines を確認します。@modelcontextprotocol/server-filesystem 2.2.0は node: '>=24' を指定しています。Node.js 22.23.4では npx が EBADENGINE の警告(stderr)を出したうえで起動しました。「一応動いた」は保証ではないので、指定された範囲に合うベースイメージを選んでください。
起動するコマンド名は、パッケージの bin 欄か、手元でインストールしたあとの node_modules/.bin で確認できます。filesystemは mcp-server-filesystem、timeは mcp-server-time です。
7. 実測した7つの落とし穴
7.1 起動時の npx -y と uvx
npx -y や uvx で起動すると、キャッシュが空のたびにパッケージを解決してダウンロードします。新しいコンテナでは、それがコールドスタートのたびに起きます。
| 起動コマンド | 1回目 | 2回目 | 3回目 |
|---|---|---|---|
npx -y …server-filesystem@2.2.0(キャッシュ空) |
2.19秒 | 2.29秒 | 2.45秒 |
| 同上(キャッシュあり) | 0.98秒 | 1.06秒 | 1.01秒 |
node …/dist/index.js(インストール済み) |
0.21秒 | 0.25秒 | 0.23秒 |
uvx mcp-server-time==2026.11.4(キャッシュ空) |
12.47秒 | タイムアウト(60秒超) | 18.52秒 |
| 同上(キャッシュあり) | 0.68秒 | 3.18秒 | 0.77秒 |
.venv/bin/mcp-server-time(インストール済み) |
0.63秒 | 0.59秒 | 0.66秒 |
時間は起動から tools/list の応答までです。埋まったキャッシュはnpmが28MB、uvが51MBで、すべて起動時にダウンロードされたものです。キャッシュがあっても npx は約1秒かかり、直接起動の4〜5倍でした。ビルド時にインストールすれば、起動の流れからネットワークが完全に消えます。
7.2 npm start がstdoutに書く
npmはスクリプトを実行するたびにバナーを出します。npm 10.9.9では、stdoutの先頭はJSON-RPCではありませんでした。
> demo-mcp@1.0.0 start
> node server.js
{"result":{"protocolVersion":"2025-11-25",...},"jsonrpc":"2.0","id":1}
MCP TypeScript SDKのクライアントは接続には成功しましたが、エラーを4件記録しました(Unexpected token '>'… と Unexpected end of JSON input)。Python SDKのクライアントもJSONの検証エラーを出したうえで接続しました。こうした「立ち直り」はクライアントの実装しだいなので、当てにしないでください。npm start --silent では何も出ず、node dist/server.js ならnpm自体を通りません。
7.3 Pythonサーバーのうっかり print()
自分のコードにも同じルールが当てはまります。読み込み時に print("Starting demo server v1...") を実行するPython SDKのサーバーでは、ハンドシェイクの前にTypeScriptクライアントでパースエラーが1件出ました(Unexpected token 'S')。ログは print(..., file=sys.stderr) か、既定でstderrに書く logging モジュールで出します。
7.4 PID 1と SIGTERM
ENTRYPOINT/CMD で起動したプロセスはコンテナ内でPID 1になり、カーネルはPID 1にシグナルの既定動作を適用しません。Node.jsのDocker向けドキュメントにも「Node.jsはPID 1として動くようには設計されておらず、Docker内で予期しない動きをする」とあります。docker stop は SIGTERM を送り、Linuxでは既定で10秒待ってから SIGKILL を送ります。
| PID 1のプロセス | SIGTERM 後の動き |
|---|---|
| シグナルハンドラーのないNodeのHTTPサーバー | 5秒後も動いたまま |
process.on('SIGTERM', …) のあるNodeのHTTPサーバー |
0.11秒で終了 |
| uvicornで動くPython SDK 2.3.0のサーバー | 0.21秒で終了(終了コード0) |
ハンドラーのないNodeサーバーを npm start で包んだもの |
0.52秒で終了 |
sh -c "node server.js; true"(シェル形式、exec なし) |
5秒後も動いたまま |
対処はどれか1つで十分です。docker run --init で起動する(Dockerは「シグナルを転送し、プロセスを回収するinitをコンテナ内で動かす」と説明しています)、サーバーを閉じる SIGTERM ハンドラーを足す、シェル形式なら最後を exec にする、のいずれかです。シェル形式の CMD node server.js は /bin/sh -c の下で動くので、表の最後の行と同じ問題が起きます。
stdioのコンテナは、クライアントがいなくなるとstdinのEOFでサーバーが終わるので、たいていこの問題を避けられます。HTTPのコンテナは避けられず、デプロイのたびに10秒止まることで、ローリングアップデートも遅れます。
7.5 -i なしで起動したstdioコンテナ
-i(「アタッチしていなくてもSTDINを開いたままにする」)を付けないと、コンテナのstdinは閉じたままで、stdioサーバーはEOFを読んで終了します。検証したTypeScript SDKのサーバーは0.15秒・終了コード0で終わりました。ホスティング先では「エラーも出さずに起動してすぐ止まるコンテナ」に見えます。手元で使うなら必ず docker run -i --rm、ホスティングするならHTTPを話すイメージにします(3章)。
-t は付けないでください。TTYを付けると改行コードが変わり、stderrがstdoutに混ざるので、stdioのルールを破ります。
7.6 ループバックでの待ち受けと無視される $PORT
コンテナ内で 127.0.0.1 に待ち受けたHTTPサーバーには、コンテナの外から届きません。また $PORT を渡すホスティング先は、そのポートでヘルスチェックをします。Python SDK 2.3.0の既定は 127.0.0.1:8000 です(5章)。起動コマンドで両方を指定してください。人気サーバーごとの既定値は、1章で紹介した事前チェックの記事にまとめています。
7.7 イメージに焼き込まれた秘密情報
Dockerのドキュメントは「ビルド引数と環境変数は、ビルドに秘密情報を渡すのに適さない」とし、理由を「最終イメージに残るから」としています。MCPサーバーのDockerfileに ENV GITHUB_TOKEN=… や ARG API_KEY を書くと、イメージを取得できる全員にキーを配ることになります。秘密情報は実行時に(docker run -e GITHUB_TOKEN)、ホスティング先のシークレット機能で、またはビルド自体に必要ならシークレットマウントで渡します。コンテナをこれ以上どこまで隔離すべきかは MCPサーバーのサンドボックス化 で解説しています。
8. コンテナをClaude・Cursor・エージェントにつなぐ
stdio用イメージは、クライアント自身が起動します。Claude Desktopの claude_desktop_config.json では次のように書きます(Cursorの mcp.json も同じ command/args の形です)。
{
"mcpServers": {
"demo": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init",
"-e", "API_KEY",
"-v", "/Users/me/projects:/data",
"demo-mcp:1.0.0"],
"env": { "API_KEY": "your-key" }
}
}
}
値を書かない -e API_KEY は、クライアントの環境変数から値をコピーします。これでキーが args に出ません。-v の左側は自分のマシンのパスで、サーバーからは /data しか見えません。
HTTP用イメージにはURLでつなぎます。docker run -d -p 8080:8080 --init demo-mcp:1.0.0 で起動してクライアントに http://localhost:8080/mcp を設定するか、イメージをデプロイして公開されたHTTPSのURLを使います。デプロイしたイメージにつながらないときは、まずHTTPステータスコードを見てください。421、406、405はそれぞれ別の層の問題を示しています。
9. Docker MCP Toolkit、自前のDockerfile、ホスティングのどれを選ぶか
MCPサーバーをコンテナで動かす方法は、自分でDockerfileを書く以外にもあります。
| 方法 | 得られるもの | 向いている場面 |
|---|---|---|
| Docker MCP CatalogとToolkit | Dockerのドキュメントによると「コンテナイメージとして配布される300以上の検証済みサーバー」をDocker Desktopから管理できる。MCP Gateway(docker mcp gateway run)がそれらを中継し、トランスポートは stdio(既定)、sse、streaming |
使いたいサーバーがカタログにあり、Dockerの入ったマシンでクライアントを使う |
| 自前のDockerfile(この記事) | バージョン、ベースイメージ、ユーザー、起動コマンドを完全に管理できる | 自作のサーバー、カタログにないサーバー、コンテナホスト向けのイメージ |
| リポジトリからビルドしてくれるMCPホスティング | Dockerfileを保守しなくてよい。ホスティング側がイメージを作って動かす | リモートのURLがほしく、イメージを自分で抱えたくない |
ToolkitとGatewayが解決するのは手元側です。自分のマシンの外にいるクライアントから使うなら、HTTP用イメージを動かす場所が別に必要です。
10. チェックリスト
- [ ] 依存パッケージはビルド時に入れ、
CMDにnpx -yやuvxがない - [ ] バージョンを固定している(ロックファイル、
==、正確なパッケージのバージョン、ベースイメージのタグ) - [ ]
ENTRYPOINT/CMDはexec形式で、npm startではなくランタイムを直接起動している - [ ] サーバーも起動処理も、JSON-RPC以外をstdoutに書かない
- [ ]
SIGTERMで止まる(--init、ハンドラー、またはexec) - [ ] 最終段階にコンパイラーや開発用の依存パッケージがない
- [ ] root以外のユーザーで動く
- [ ]
.dockerignoreで.env、.git、node_modules、手元のビルド結果を除外している - [ ]
ARGやENVに秘密情報がなく、実行時に渡している - [ ] ベースイメージがサーバーの指定するランタイム(
engines、requires-python)に合っている - [ ] stdio用:クライアントは
docker run -i --rmで起動し、-tを付けていない - [ ] HTTP用:
0.0.0.0で待ち受け、$PORTを読み、HEALTHCHECKがある - [ ] クライアントをつなぐ前に、コンテナへ実際に
tools/listを送った
11. トラブルシューティング(症状→原因→対処)
| 症状 | 考えられる原因 | 対処 |
|---|---|---|
| コンテナが起動してすぐ終了コード0で終わる | stdioサーバーがstdinでEOFを受け取った | -i を付ける。ホスティングならHTTP用イメージにする |
クライアントに Unexpected token '>' が出る |
npm start のバナーがstdoutに出ている |
ENTRYPOINT ["node", "dist/server.js"] か npm start --silent |
自分の書いた文字列で Unexpected token が出る |
print()/console.log() がstdoutに出ている |
ログはstderrへ |
docker stop が毎回10秒かかる |
PID 1のNode.jsが SIGTERM を無視している |
--init、SIGTERM ハンドラー、exec形式の CMD |
| コールドスタート直後の呼び出しがタイムアウトする | 起動時に npx/uvx がダウンロードしている |
ビルド時にインストールする |
| コンテナ内では動くのに外からは「connection refused」 | HTTPサーバーが 127.0.0.1 で待ち受けている |
0.0.0.0 で待ち受ける |
| ログは正常なのにヘルスチェックが失敗する | サーバーが $PORT を無視している |
$PORT の値でポートを指定する |
HEALTHCHECK が「curl: not found」で失敗する |
slim系イメージにcurlがない | node/python のチェックスクリプトを使う |
インストール時に EBADENGINE の警告が出る |
ベースイメージが engines.node より古い |
指定範囲に合うベースイメージにする |
| イメージが想定より大きい | 最終段階に開発用の依存やビルドツールが残っている | マルチステージビルド、npm prune --omit=dev |
docker history にキーが見える |
秘密情報を ARG/ENV で渡した |
それを外して再ビルドし、キーを再発行して実行時に渡す |
12. NodeFlareならこう解決できる
NodeFlareは、GitHubリポジトリからMCPサーバー(stdioだけのサーバーも含む)をビルドして動かし、認証付きのHTTPSエンドポイントにするMCP Hostingサービスです。この記事で挙げた課題には、次のように対応しています。
| この記事の課題 | NodeFlareでの対応 |
|---|---|
| Dockerfileを書いて保守する手間 | リポジトリからNode.js、Python、Go、Rust、Java、C#/.NET、Dockerを判定し、ランタイムごとにDockerfileを生成します。持ち込んだDockerfileは検証したうえでラップします。モノレポのサブディレクトリにも対応しています |
誤った起動コマンド(npm start、npx) |
明示したエントリーコマンドとビルドコマンドが常に自動判定より優先されるので、node dist/server.js を直接起動できます |
| HTTPを話せないstdioサーバー | stdio-adapter.cjs という1ファイルがサーバーを子プロセスとして起動し、https://<your-server>.nodeflare.tech/mcp でStreamable HTTP(旧HTTP+SSEも)として公開します |
| 起動後にクラッシュするサーバー | クラッシュ時は1秒から30秒までの指数バックオフで再起動します。デプロイのたびに実際のMCP initialize で確認し(バックオフ付きで最大8回)、クラッシュを繰り返すとデプロイを失敗にします |
EBADENGINE や足りないシステムツール |
ロックファイルの engines.node が新しいメジャーを求めると、Node.jsのバージョンを自動で上げます。足りないビルドツールは許可リストからインストールし、最大3回までビルドをやり直します |
| ビルド引数やイメージレイヤーに残る秘密情報 | 環境変数は暗号化して保存し、VMの起動時にだけ注入します。ビルド引数、イメージレイヤー、ログには残らず、ビルドログも既知のトークン形式を伏せ字にします |
| ダウンロードによるコールドスタート | 数分アイドルが続くとサーバーをスナップショットして停止し、1秒未満で復元します。停止中の料金は0円です |
| イメージに合うメモリサイズ選び | サーバーごとに256MB、512MB、1GB、2GBから選べます(上限はプランによります) |
料金:Freeは0円で、MCPサーバー1つと月30 GB-hoursのコンピュート。Proは月額2,980円で、サーバー数無制限、300 GB-hoursと10GBのストレージ込み、超過分のコンピュートは1 GB-hourあたり5円です。
最小の始め方:
- nodeflare.tech にGitHubでサインインし、MCPサーバーのリポジトリ(とサブディレクトリ)を選ぶ。
- 環境変数を登録し、
npm startやnpxを避けたい場合はエントリーコマンドを指定する。 - デプロイして確認済みの状態になったら、
/mcpのURLとAPIキーをクライアントに貼る。
1サーバーまで無料で試せます → nodeflare.tech
13. よくある質問
MCPサーバーをDockerで動かすには?
ビルド時にサーバーをインストールしてexec形式の ENTRYPOINT で起動するイメージを作り、クライアントから docker run -i --rm <イメージ> で起動させます。-i はstdinを開いたままにするためのもので、ないとstdioサーバーはEOFを読んですぐ終わります。リモートで使うなら、HTTP用イメージを作ってポートを公開します。
MCPサーバーのコンテナがすぐ終了するのはなぜ?
多くの場合、stdioサーバーを -i なしで起動したため、stdinが閉じていてEOFで終了しています。検証では0.15秒・終了コード0で終わりました。手元なら -i を付けます。stdinをつながないホスティング先では、Streamable HTTPを話すイメージにするか、ブリッジを入れる必要があります。
MCPサーバーのDockerfileでnpxを使ってもいい?
おすすめしません。npx -y はキャッシュが空のたびにパッケージをダウンロードし、新しいコンテナではそれがコールドスタートのたびに起きます。検証ではキャッシュが空だと最初の応答まで2.2〜2.4秒、インストール済みのコマンドなら0.2秒でした。ビルド時に npm install -g で正確なバージョンを入れ、そのコマンドを起動します。
npm start でstdioのMCPサーバーが壊れるのはなぜ?
npmはサーバーが起動する前に、> 名前@バージョン start と実行コマンドのバナーをstdoutに出すからです。MCPの仕様は、MCPメッセージ以外をstdoutに書くことを禁じています。検証ではTypeScript SDKのクライアントがパースエラーを4件記録しました。エントリーポイントを node dist/server.js にするか、npm start --silent を使います。
MCPサーバーのコンテナに --init は必要?
SIGTERM ハンドラーを持たずにPID 1で動くNode.jsのサーバーには、--init かそれに代わる対策が必要です。検証用サーバーはPID 1で SIGTERM を無視したので、docker stop は10秒待ってから強制終了することになります。ハンドラーか --init で解決し、uvicornで動くPython SDKのサーバーは最初から0.21秒で止まりました。
MCPサーバーのベースイメージは何を選べばいい?
サーバーが指定するバージョン範囲に合う、公式ランタイムのslim版を選びます。たとえばNode.js 24以上を求める @modelcontextprotocol/server-filesystem 2.2.0なら node:24-slim、Pythonのサーバーなら python:3.13-slim です。タグを固定し、マルチステージビルドでコンパイラーを最終イメージから外します。
DockerのMCPサーバーにAPIキーを渡すには?
Dockerfileではなく、実行時に渡します。クライアントの設定では args に -e API_KEY と書き、値は env ブロックに書きます。こうするとDockerがクライアントの環境から値をコピーします。Dockerのドキュメントは、ビルド引数や ENV の値が最終イメージに残ると注意しています。
MCPサーバーのコンテナにヘルスチェックを付けるには?
HTTP用イメージなら、/mcp に server/discover をPOSTして200かを確かめる HEALTHCHECK を足します。2026-07-28版のサーバーは必ずこれに答えます。slim系イメージにはcurlがないので、チェックはNode.jsかPythonで書きます。stdio用イメージはクライアントがプロセスを管理するので、ヘルスチェックは要りません。
MCPサーバーのDockerイメージはどのくらいの大きさ?
ベースイメージに比べると、依存パッケージは小さめです。検証ではTypeScript SDKのサーバーの本番用 node_modules が26MB(開発用を削る前は63MB)、mcp 2.3.0を入れたPythonの仮想環境が39MBでした。ブラウザを使うサーバーは別で、Chromiumとそのライブラリが上乗せされます。
Docker MCP ToolkitはMCPサーバーのホスティングと同じもの?
違います。DockerのMCP CatalogとToolkitは、Dockerの入ったマシン上でカタログのサーバーをコンテナとして動かし、MCP Gatewayが手元のクライアントへ中継するものです。Web版Claudeやクラウドのエージェントなど外にいるクライアントから使うには、インターネットから届くHTTPエンドポイントが別に必要です。
まとめ
MCPサーバーのDockerfileは、普通のDockerfileに3つのルールを足したものです。stdoutはJSON-RPC専用にする、すべてビルド時に入れる、SIGTERM できちんと止まる、の3つです。検証では、npx -y と uvx がコールドスタートのたびに数秒を足し(uvx は1回タイムアウト)、npm start がハンドシェイクの前にJSONでない行を4行出し、PID 1のNode.jsが SIGTERM を無視し、-i なしのstdioコンテナが0.15秒で終わり、マルチステージビルドで依存が63MBから26MBに減りました。ランタイムをexec形式で直接起動し、root以外で動かし、秘密情報は実行時に渡し、クライアントをつなぐ前にコンテナへ実際に tools/list を1回送ってください。
参考資料
- MCP仕様 2025-11-25:Transports(stdio)
- MCP仕様 2026-07-28:Transports
- Node.js Docker best practices(nodejs/docker-node)
- Docker:docker container run リファレンス
- Docker:docker container stop リファレンス
- Docker:Build secrets
- Docker:Multi-stage builds
- Docker:MCP Catalog and Toolkit
- Docker:docker mcp gateway run
- MCP TypeScript SDK
- MCP Python SDK
- modelcontextprotocol/servers
