記事一覧
MCPホスティング

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-filesystem 2.2.0、mcp-server-time 2026.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で見つけたサーバー)にあります。

目次

  1. MCPサーバーのDockerfileがやるべきこと
  2. 検証の方法
  3. stdio用イメージとHTTP用イメージ
  4. Node.js/TypeScriptのMCPサーバー用Dockerfile
  5. PythonのMCPサーバー用Dockerfile
  6. GitHubで見つけたMCPサーバー用Dockerfile
  7. 実測した7つの落とし穴
  8. コンテナをClaude・Cursor・エージェントにつなぐ
  9. Docker MCP Toolkit、自前のDockerfile、ホスティングのどれを選ぶか
  10. チェックリスト
  11. トラブルシューティング(症状→原因→対処)
  12. NodeFlareならこう解決できる
  13. よくある質問

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円です。

最小の始め方:

  1. nodeflare.tech にGitHubでサインインし、MCPサーバーのリポジトリ(とサブディレクトリ)を選ぶ。
  2. 環境変数を登録し、npm start や npx を避けたい場合はエントリーコマンドを指定する。
  3. デプロイして確認済みの状態になったら、/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回送ってください。

参考資料

NodeFlare

MCP専用ホスティングサービス

GitHubにあるMCPを簡単デプロイ・簡単運用で最適化
無料で始める

他の記事

MCPトークン2026年11月17日

ツール引数は出力トークン:MCPのトークン消費で見落とされる「書く側」のコスト(write_fileとedit_fileを実測・2026年版)

MCPのツール引数は出力トークンで、単価は入力の5倍、キャッシュも効きません。公式Filesystemサーバーで1行の変更がwrite_file 5,549トークン対edit_file 49トークンになった実測、Sonnet 5.5・Opus 5.5・Fable 5.2での料金試算、ツール間の書き写し、max_tokensでの中断、書き直しの損益分岐、置換ツールのコードまで。

MCPセキュリティ2026年11月17日

MCPのきめ細かな認可:スコープでは防げないBOLAを、オブジェクト・引数・項目単位のチェックで止める【MCP Security 2026】

ツール単位のスコープでは防げない、MCPツールのオブジェクト・引数・項目単位の認可を解説。仕様の「スコープだけで十分とみなすのは誤り」、公式Python SDKを含む2026年のCVE3件、チェックの置き場所、8つのルール、検証済みPythonコード(スコープのみ4/14、多層14/14)とCedarポリシー(12/12)。

MCPホスティング2026年11月17日

Hugging Face SpacesはまだMCP Hostingに無料で使える?Gradioのmcp_server=Trueを2026年の有料化後に検証(Gradio 6.32)

2026年のHugging Face SpacesでのMCP Hosting。新規のGradio SpaceはZeroGPU以外PROが必要、無料ハードウェアは48時間でスリープ、Gradioのキューは既定で1件ずつ。Gradio 6.32で検証した /gradio_api/mcp/ の使い方、188 MB・1回約60 msの実測、Space名の接頭辞、ZeroGPUの上限、費用、Claude Code・Cursorの接続を解説。

MCPサーバーのDockerfile完全ガイド:Node.js・Python用テンプレートと実測した7つの落とし穴【MCP Hosting 2026】 | Blog | Nodeflare