stdio サーバーを公開する¶

ゴール：ホスト上の stdio MCP サーバーを HTTPS の Streamable HTTP エンドポイントにして、リモートの MCP クライアント——Claude Desktop、 Claude Code、さらに Claude.ai のカスタムコネクタ——から使えるようにする。各ユーザーは専用の子プロセスに隔離され、本物の OAuth 2.1 ログインで守られます。

1. ループバックで動作確認¶

mcp-stdio serve --enable-oauth --public-url http://127.0.0.1:8080 \
  --dev-user alice --port 8080 -- python -m my_mcp_server

別のターミナルから、mcp-stdio 自身のクライアントモードで接続します：

mcp-stdio --check --oauth http://127.0.0.1:8080/mcp

--dev-user はループバック検証専用の非セキュアな代用アイデンティティです——本物のログインなしで OAuth フロー全体を通せます。--check が initialize 成功を報告すればゲートウェイは動いています。ここから先はデプロイの話だけです。

2. リバースプロキシの背後にデプロイ¶

本番ではアイデンティティは SSO から来ます。TLS 終端と認証はリバースプロキシ（nginx、Apache など）に任せ、ログイン済みユーザーを信頼できるヘッダーで mcp-stdio に渡します：

mcp-stdio serve --enable-oauth \
  --public-url https://mcp.example.com \
  --trusted-user-header X-Forwarded-User \
  --token-store /var/lib/mcp-stdio/state.json \
  --session-idle-ttl 180 \
  -- python -m my_mcp_server

--public-url は OAuth issuer を公開アドレスに固定します（プロキシ背後では必須）。
--trusted-user-header はプロキシが設定し、かつクライアント由来の同名ヘッダーを剥がすヘッダー名です——その剥がしこそが信頼の根拠です。
--token-store は発行済みトークン・クライアント登録・replay 検知の台帳を永続化（0600）し、再起動やデプロイで全ユーザーがログアウトされるのを防ぎます。これがないとデプロイのたびに全トークンが無効に。パスは serve プロセスごとに 1 つ——sidecar の .lock が誤共有を起動時に拒否します。
--session-idle-ttl は、切断処理なしに消えたクライアントの子プロセスを回収します。

接続ユーザーごとに得られるもの：専用の子プロセス（initialize で spawn、切断か idle タイムアウトで破棄）、認証済みアイデンティティに束縛されたセッション——他人のセッション id を提示しても 404 で、越境はできません。

3. オプションの追加機能¶

こうしたい	こうする
Claude.ai カスタムコネクタ（ブラウザベースのクライアント）	`--allow-redirect-uri https://claude.ai/api/mcp/auth_callback`
1 ホストに複数バックエンド	バックエンドごとに serve プロセスを分け、パススコープ issuer を使う：`--public-url https://mcp.example.com/team-a`、`…/team-b`——AS エンドポイントと well-known もプレフィックス配下に収まります
同時ユーザー数の上限	`--max-sessions N`（既定 100。超過した `initialize` は `503`）
OAuth の代わりに静的トークン	`--enable-oauth` を外して `MCP_STDIO_SERVE_TOKEN` を設定
アクセストークンの寿命を調整	`--access-token-ttl SECONDS`（既定 3600）

運用者向けメモ¶

内蔵の認可サーバーは Dynamic Client Registration、PKCE（S256 のみ）、 replay 検知付き refresh ローテーション、RFC 8707 の audience 束縛を実装しています。MCP クライアントは標準の well-known ドキュメント経由ですべてを自動発見するので、クライアント側の設定は不要です。
--token-store のファイルは秘密鍵と同様に扱ってください。0700 のディレクトリに 0600 で作成されます。
全リクエストはクエリ文字列を redact した形で stderr にログされます。

実運用の参照例：この構成そのままで、1 ホスト配下に複数の stdio MCP サーバーを公開し、定常的な再デプロイをユーザーに気づかれずに乗り切っています。子プロセスの内側でユーザーごとの資格情報が必要なら、それはあなたのサーバーの設計判断です——ゲートウェイは意図的にアイデンティティを子へ注入しません。