リモートMCPサーバーに接続できない?エラーコード別の原因と直し方【MCP Hosting・2026-07-28仕様で20通り検証】
デプロイしたMCPサーバーが421・406・405・307・404・401や-32020/-32022付きの400を返す理由を、MCP Python SDK 2.3.0に20通りのリクエストを送って検証。ステータス別の対処表、HostヘッダーとCORSの直し方、OAuth検出の確認点、curlでの5段階の切り分けをまとめました。
最終更新:2026年11月4日 / 対象:MCP仕様 2026-07-28(Streamable HTTP、Authorization、Versioning)、MCP Python SDK 2.3.0(
MCPServer)+uvicorn、StarletteのCORSMiddleware。本文のリクエストはすべて2026年11月4日にcurlでローカルの検証用サーバーへ送ったものです。
結論(30秒で読める要約)
MCP Hostingでデプロイしたリモートサーバーに接続できないときは、HTTPステータスコードを見れば「どの層が断ったか」が分かり、ほとんどの場合、原因は1つに絞れます。MCP Python SDK 2.3.0のサーバーに正常・異常あわせて20種類のリクエストを送り、返ってきた内容をすべて記録しました。
- デプロイ後にだけ起きる失敗で一番多いのは
421 Invalid Host headerです。SDKのStreamable HTTPアプリは、既定の設定だと127.0.0.1とlocalhostだけを許可するDNSリバインディング対策が有効になります。そのため、プロキシや独自ドメイン経由でHost: mcp.example.comが届いた時点で421になります。allowed_hostsを設定するか、ホストを検証するプロキシの後ろでhost="0.0.0.0"を指定して直します。 406はAcceptヘッダーの誤りです。仕様ではapplication/jsonとtext/event-streamの両方が必須です。既定のSSE応答のサーバーにAccept: application/jsonだけを送ると406でした。- JSON-RPCの
-32020付きの400は、ヘッダーと本文の食い違いです。Mcp-Method、Mcp-Name、MCP-Protocol-Versionのどれかが欠けているか、本文と一致していません。-32022はプロトコルバージョンそのものが非対応という意味です。 400 "Missing session ID"は、セッション時代(2025-11-25以前)のクライアントがinitializeを送らずにリクエストした状態です。pingに404 -32601が返るのは、2026-07-28で削除されたメソッドを使っているためです。404、405、307はURLの問題です。パスの間違い、POSTではなくGET、末尾スラッシュによるリダイレクト(TLSプロキシの後ろではhttp://に落ちることもある)が原因です。- ブラウザで動くクライアントがCORSエラーになるのは、サーバーが
OPTIONSのプリフライトに405を返すからです。MCPのヘッダーを許可するCORSミドルウェアを追加します。 401と403は認可の層から返ります。仕様どおりの401にはresource_metadata付きのWWW-Authenticateがあり、クライアントはこれを使ってOAuthの設定を探します。
検証結果の一覧は3章、ステータスコード別の対処表は4章にあります。
目次
- リモートMCPの接続エラーとは
- まず「どの層が返したか」を見る
- 検証:20種類のリクエストとサーバーの応答
- エラーコード早見表:ステータス → 原因 → 対処
- デプロイ後にだけ起きる3つの失敗
- 401と403:認可とOAuthの自動検出
- バージョンと世代の食い違い
- サーバーではなくMCP Hostingの基盤が返すエラー
- curlで5段階に切り分ける
- チェックリスト
- NodeFlareならこう解決できる
- よくある質問(FAQ)
1. リモートMCPの接続エラーとは
リモートMCPの接続エラーとは、クライアント(Claude、Cursor、VS Code、エージェントSDKなど)が、リモート用のトランスポートであるStreamable HTTPでMCPサーバーへのJSON-RPCリクエストを完了できない状態のことです。クライアントの画面には「接続に失敗しました」「サーバーが切断されました」程度しか出ないことが多いため、手がかりになるのは生のHTTPステータスと本文です。同じリクエストをcurlで送れば確認できます。
2026-07-28仕様では、クライアントのリクエストはすべて1つのMCPエンドポイント(通常は /mcp)へのPOSTで、決まったヘッダーを付ける必要があります。そのため、エラーの多くは予測できます。
| ヘッダー | 2026-07-28仕様での決まり | 誤っていたときの結果 |
|---|---|---|
Accept |
application/json と text/event-stream の両方を含めるのがMUST |
SDKでは406 |
Content-Type |
仕様の例はすべて application/json |
SDKでは400 Invalid Content-Type header |
MCP-Protocol-Version |
すべてのPOSTに必須で、_meta と一致させる |
400、-32020(HeaderMismatch) |
Mcp-Method |
すべてのリクエストに必須。本文の method と同じ値 |
400、-32020 |
Mcp-Name |
tools/call、resources/read、prompts/get で必須 |
400、-32020 |
Origin |
サーバーは検証しなければならない(MUST) | 403 |
Authorization |
認可を使う場合は毎回必須。クエリ文字列に入れてはいけない | 401 |
そもそもそのサーバーをリモートで動かせるかをまだ確かめていない場合は、先にMCP Hostingの適合チェックを見てください。この記事は、デプロイが済んでURLはあるのに、クライアントからつながらない段階を扱います。
2. まず「どの層が返したか」を見る
接続エラーを最短で直すには、そのエラーをどの層が返したかを先に特定します。層ごとに考えられる原因は数個しかありません。
| 層 | よくある応答 | 見分け方 |
|---|---|---|
| DNS・TLS・ネットワーク | HTTPステータスなし(接続拒否、タイムアウト、証明書エラー) | curlがステータスを表示する前に失敗する |
| プラットフォーム・リバースプロキシ | 404(ルート)、413、429、502、503、504 | HTMLやプレーンテキスト、プラットフォームのエラーページ |
| 認証ゲートウェイ・サーバーの認可 | 401、403 | WWW-Authenticate ヘッダーがある |
| MCPサーバーのHTTPトランスポート | 307、400(Content-Type)、403(Origin)、405、406、421 | 本文が空かプレーンテキストで、JSON-RPCではない |
| MCPプロトコル層 | JSON-RPCの error 付きの400または404 |
-32020、-32022、-32601、-32700 を含むJSON |
| ツール層 | "isError": true 付きの200 |
接続はできていて、ツールが失敗している |
最後の行は接続エラーではありません。200で isError: true が返るなら接続には成功しており、問題はツールの中(期限切れの外部APIキーなど)にあります。
3. 検証:20種類のリクエストとサーバーの応答
ツールを1つ(echo)だけ持つMCPサーバーをMCP Python SDK 2.3.0で作り、2つの設定で起動して同じリクエストを送りました。Aは mcp.streamable_http_app() をすべて既定値で使ったもの(SSE応答、host="127.0.0.1")、Bは mcp.streamable_http_app(json_response=True, host="0.0.0.0") です。特に書いていない行は、正しい2026-07-28ヘッダーを付けた /mcp へのPOSTで、本文は tools/list です。
| # | リクエスト | A:既定値 | B:json_response、host 0.0.0.0 |
|---|---|---|---|
| 1 | 正しいリクエスト | 200 | 200 |
| 2 | Host: mcp.example.com(プロキシや独自ドメイン経由を想定) |
421 Invalid Host header |
200 |
| 3 | Origin: https://evil.example |
403 Invalid Origin header |
200 |
| 4 | /mcp ではなく / にPOST |
404 | 404 |
| 5 | /mcp/(末尾スラッシュ)にPOST |
307で /mcp へ |
307で /mcp へ |
| 6 | /sse(旧SSEのパス)にPOST |
404 | 404 |
| 7 | /mcp にGET |
405、Allow: POST |
405、Allow: POST |
| 8 | Accept: application/json のみ |
406 | 200 |
| 9 | Accept ヘッダーなし |
406 | 406 |
| 10 | Content-Type: text/plain |
400 Invalid Content-Type header |
400 |
| 11 | Mcp-Method なし |
400、-32020 |
400、-32020 |
| 12 | 本文は tools/list で Mcp-Method: tools/call |
400、-32020 |
400、-32020 |
| 13 | ヘッダーは 2099-01-01、本文は2026-07-28 |
400、-32020 |
400、-32020 |
| 14 | ヘッダーも本文も 2099-01-01 |
未実施 | 400、-32022、supported: ["2026-07-28"] |
| 15 | Mcp-Name なしの tools/call |
未実施 | 400、-32020(mcp-name header does not match) |
| 16 | Mcp-Name: echo 付きの tools/call |
未実施 | 200 |
| 17 | ping(2026-07-28で削除) |
未実施 | 404、-32601(Method not found) |
| 18 | 旧形式の initialize(2025-11-25)、バージョンヘッダーなし |
200、protocolVersion: "2025-11-25" |
200 |
| 19 | 旧形式の tools/list(セッションなし、MCPヘッダーなし) |
400 Missing session ID |
400 Missing session ID |
| 20 | 壊れたJSON | 400、-32700(Parse error) |
400、-32700 |
結果から分かること:
- 同じコードでも、動かす場所で応答が変わります。設定Aは手元では動き、プロキシの後ろに置くと失敗します(2行目)。サーバーがリクエストを読む前に
Hostヘッダーで拒否するので、クライアント側の設定では直せません。 - ヘッダー関係のエラーには、JSON-RPCの本文がなくプレーンテキストだけのものがあります(2、3、8〜10行目)。JSON-RPCのエラーしか解釈しないクライアントでは「接続失敗」としか表示されません。生の応答を確認してください。
- ヘッダーの照合は厳密です。
Mcp-Methodがないときも、値が違うときと同じ-32020になります(11、12行目)。バージョンヘッダーが本文と食い違う場合も-32022ではなく-32020です(13行目)。-32022になるのは、ヘッダーと本文が一致していて、そのバージョンにサーバーが対応していない場合だけでした(14行目)。 - 旧世代のクライアントもつながりますが、
initializeを送った場合に限ります。2025-11-25のinitializeには通常どおり応答し(18行目)、それを省いた旧形式のリクエストは拒否しました(19行目)。
4. エラーコード早見表:ステータス → 原因 → 対処
ステータスコードが分かっていて、最短で直したいときはこの表を使ってください。「仕様」欄は2026-07-28仕様に定めがある場合にその記述を要約し、SDK独自の動作はそう明記しています。
| ステータス | 本文・エラーコード | 仕様 | よくある原因 | 対処 |
|---|---|---|---|---|
| 307 | 空、Location: .../mcp |
定めなし(フレームワークのリダイレクト) | URLが /mcp/ で終わっている |
クライアント設定の末尾スラッシュを消す |
| 400 | Invalid Content-Type header |
定めなし(SDK) | クライアントやプロキシがJSON以外の Content-Type を送っている |
Content-Type: application/json を送る |
| 400 | -32020(HeaderMismatch) |
400とHeaderMismatchを返すのがMUST | Mcp-Method、Mcp-Name、MCP-Protocol-Version が欠けている・本文と違う。プロキシが独自ヘッダーを削っている |
method、params.name、バージョンをヘッダーにも入れる。プロキシが転送しているか確認する |
| 400 | -32022(UnsupportedProtocolVersion) |
400を返すのがMUST。クライアントは supported から共通の版を選んで再送するのがSHOULD |
共通して対応している版がない | クライアントかサーバーのSDKを更新する。data.supported を読む |
| 400 | -32600、Missing session ID |
旧世代(セッションあり)の動作 | セッション時代のクライアントが initialize を省いた。監視やスクリプトが2026-07-28のヘッダーなしで送っている |
2026-07-28のヘッダーと _meta を付ける。旧サーバーなら先に initialize を送る |
| 400 | -32700(Parse error) |
JSON-RPC | 本文が正しいJSONではない(シェルのクォートが原因のことが多い) | 本文を検証する。curlでは --data @file.json を使う |
| 401 | WWW-Authenticate: Bearer resource_metadata=... |
無効・期限切れのトークンには401を返すのがMUST | トークンがない、期限切れ、別サーバー向け(audience違い) | Authorization: Bearer ... を送る。OAuthをやり直す。6章参照 |
| 403 | Invalid Origin header |
不正なOriginには403を返すのがMUST | 許可していないオリジンのブラウザ型クライアント | allowed_origins に追加する |
| 403 | WWW-Authenticate: ... error="insufficient_scope" |
403を返すのがSHOULD | このツールに必要なスコープがトークンにない | チャレンジに書かれたスコープで認可し直す |
| 404 | Not Found(JSON-RPCなし) |
定めなし | パスの間違い(/ と /mcp、旧 /sse のURL) |
エンドポイントのパスを正確に指定する |
| 404 | -32601(Method not found) |
404と -32601 を返すのがMUST |
削除されたメソッド(ping)や未実装のメソッド |
ping の代わりに server/discover を使う。クライアントを更新する |
| 405 | 空、Allow: POST |
2026-07-28専用のサーバーはGET・DELETEに405を返すのがSHOULD | GETで送っている(ブラウザでの確認、旧SSEクライアント、死活監視)。CORSのプリフライト | POSTを使う。OPTIONS をCORSで処理する(5章) |
| 406 | 空 | 定めなし(SDK)。仕様では Accept に両方が必須 |
Accept に text/event-stream(または両方)がない |
Accept: application/json, text/event-stream を送る |
| 421 | Invalid Host header |
定めなし(SDKのDNSリバインディング対策) | サーバーがlocalhostの Host しか許可していない |
allowed_hosts を設定する。プロキシの後ろなら host="0.0.0.0" |
| 429 | プラットフォームによる | 定めなし | プラットフォーム、ゲートウェイ、上流APIのレート制限 | 間隔を空けて再送する。キーやIPごとの上限を確認する |
| 502 / 503 / 504 | 多くはプラットフォームのHTML | 定めなし | プロセスが落ちた、待ち受けていない、起動中、処理に時間がかかりすぎた | ログ、待ち受けアドレス、ポート、タイムアウトを確認する(8章) |
逆に、2026-07-28のサーバーでは出なくなったコードもあります。セッションがないので「404はセッション切れなので再度initializeする」という以前の決まりは当てはまりません。また ping がなくなったので、pingに404が返るのは正しい動作です。
5. デプロイ後にだけ起きる3つの失敗
次の3つは localhost で試している間は一度も出ません。「手元では動くのにリモートだとつながらない」原因として最も多いのはこのためです。
5.1 421 Invalid Host header
transport_security を渡さず、既定の host="127.0.0.1" のまま streamable_http_app() を呼ぶと、Python SDKはDNSリバインディング対策を有効にし、許可するホストを 127.0.0.1:*、localhost:*、[::1]:* だけにします。リバースプロキシ、プラットフォームのルーター、独自ドメインを経由したリクエストには公開ホスト名が入っているため、421になります。直し方は2つあり、どちらも検証しました。
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings
mcp = MCPServer("my-server")
# 方法1:対策は残したまま、実際のホスト名を許可する
app = mcp.streamable_http_app(transport_security=TransportSecuritySettings(
enable_dns_rebinding_protection=True,
allowed_hosts=["mcp.example.com", "127.0.0.1:*"],
allowed_origins=["https://app.example.com"],
))
# 方法2:ホストを検証するプロキシの後ろに置く場合
app = mcp.streamable_http_app(host="0.0.0.0")
方法1では Host: mcp.example.com が200になりました。方法2は Origin の検証も外れます(3章の3行目が200になった)。仕様ではサーバーが Origin を検証するのはMUSTなので、方法2は前段で Origin を検証している場合だけにしてください。
5.2 307と末尾スラッシュ
/mcp/ へのPOSTは、/mcp への 307 Temporary Redirect になりました。307はメソッドと本文を保ったままなので、curlの -L ならたどれますが、POSTのリダイレクトをたどらないMCPクライアントもあります。さらにTLSを終端するプロキシの後ろでは、Location ヘッダーはサーバーから見えた情報で組み立てられます。X-Forwarded-Proto: https があれば https://mcp.example.com/mcp を指しましたが、このヘッダーがなければ http:// のURLになります。エンドポイントは末尾スラッシュなしで正確にコピーし、プロキシの後ろではuvicornの --forwarded-allow-ips を設定してプロキシの X-Forwarded-Proto を信頼させます。
5.3 CORS:ブラウザのプリフライトが405になる
ブラウザで動くクライアント(Web上のエージェント、MCP InspectorのブラウザUI、自作のWebアプリ)は、MCPのリクエストが独自ヘッダーを使うため、POSTの前に OPTIONS のプリフライトを送ります。検証したサーバーはプリフライトに405を返し、Access-Control-* ヘッダーも付けませんでした。ブラウザはこれを405ではなくCORSエラーとして表示します。StarletteのCORSミドルウェアを追加すると直りました。
from starlette.middleware.cors import CORSMiddleware
app = mcp.streamable_http_app(json_response=True, host="0.0.0.0")
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["POST", "OPTIONS"],
allow_headers=["content-type", "accept", "authorization",
"mcp-protocol-version", "mcp-method", "mcp-name"],
expose_headers=["www-authenticate"],
)
変更後、プリフライトは200で access-control-allow-origin: https://app.example.com を返しました。ただし検証で1つ落とし穴が見つかりました。mcp-param-region を要求するプリフライトは400になります。x-mcp-header 付きの引数を持つツールでは、クライアントが Mcp-Param-{Name} ヘッダーを送るので、これも許可が必要です。また www-authenticate を公開しないと、ブラウザ型クライアントは401のOAuthチャレンジを読めません。デスクトップアプリやCLIのクライアントはプリフライトを送らないので、CORSエラーが出たらブラウザ型のクライアントだと考えて構いません。
6. 401と403:認可とOAuthの自動検出
401は有効なトークンがないこと、403はトークン自体は有効でも許可されていないこと(またはオリジンが拒否されたこと)を表します。どちらも仕様に定めがあり、応答のヘッダーがクライアントの次の動きを決めます。
| 応答 | 仕様上の意味 | クライアントの次の動き |
|---|---|---|
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource" 付きの401 |
認可が必要、またはトークンが無効・期限切れ | Protected Resource Metadataを取得し、認可サーバーを見つけてOAuthを実行する |
WWW-Authenticate なしの401 |
well-knownのメタデータを置いている場合だけ仕様上許される | /.well-known/oauth-protected-resource/<パス>、次に /.well-known/oauth-protected-resource を試す |
error="insufficient_scope", scope="..." 付きの403 |
スコープが足りない | チャレンジのスコープで認可し直す。仕様ではチャレンジのスコープを正とするのがMUST |
403 Invalid Origin header |
オリジンの拒否(認可の問題ではない) | サーバーの allowed_origins を直す |
OAuthで失敗するときの確認点:
- Protected Resource Metadata:サーバーは
WWW-Authenticateにresource_metadataを入れるか、well-knownのURIを置くかのどちらかがMUSTです。クライアントはパス付きの形(/mcpなら/.well-known/oauth-protected-resource/mcp)を先に、ルートの形を後に試します。 - 認可サーバーのメタデータ:クライアントは
/.well-known/oauth-authorization-server、次に/.well-known/openid-configurationを試します(issuerにパスがある場合はパス付きの形も)。文書内のissuerが取得元のURLと一致しなければ、クライアントはそのメタデータを使ってはいけません(MUST NOT)。 - audience:クライアントは
resourceパラメーターを送るのがMUSTで、サーバーは自分宛てに発行されていないトークンを拒否するのがMUSTです。別のサーバー向けのトークンは、そちらでは有効でも401になります。 - URLにトークンを入れない:仕様ではクエリ文字列にトークンを入れてはいけません(MUST NOT)。
?api_key=を付ける設定は、ヘッダーを期待するサーバーで401になる典型例です。
クライアントごとのヘッダーの書き方やOAuthの始め方はリモートMCPクライアント設定チートシートにまとめています。サーバー側のOAuthを実装する場合はMCP OAuthサーバー実装の7ステップを参照してください。
7. バージョンと世代の食い違い
プロトコルの世代が違うクライアントとサーバーでも、クライアントがフォールバックに対応していれば接続できます。2026-07-28仕様の記述は次のとおりです。
| 状況 | サーバーの応答 | 期待されるクライアントの動き |
|---|---|---|
| 両方2026-07-28だが、対応版の一覧が違う | 400、-32022、data.supported |
supported から版を選んで再送する |
| 2026-07-28のクライアントと2025-11-25のサーバー | 新しい形式のJSON-RPCエラーを含まない400 | initialize にフォールバックする |
| 2026-07-28のクライアントと2024-11-05のHTTP+SSEサーバー | 新しい形式のエラーを含まない400・404・405 | GETにフォールバックして endpoint イベントを待つ |
| 2025-11-25のクライアントと2026-07-28専用のサーバー | ヘッダー不足で400 | 互換表では「失敗」。クライアントを更新する |
| セッション時代の前提で書いたスクリプトや監視 | 400 Missing session ID、ping には404 -32601 |
2026-07-28のヘッダーと server/discover で書き直す |
仕様には、クライアントは判定した世代をオリジンごとにキャッシュするのがSHOULDともあります。サーバーをその場で更新したあと古いクライアントが失敗し続けるなら、クライアントを再起動して世代を判定し直させてください。
8. サーバーではなくMCP Hostingの基盤が返すエラー
5xxやタイムアウトは、多くの場合サーバーの前にあるプラットフォームが返していて、サーバー自身のログには何も残りません。
| 症状 | よくある原因 | 最初に見るところ |
|---|---|---|
| デプロイ直後から502 | プロセスが 127.0.0.1 や別のポートで待ち受けている |
0.0.0.0 で待ち受け、$PORT を読む |
| アイドル後の最初のリクエストだけ503 | インスタンスがゼロから起動中 | クライアントのタイムアウトを延ばす |
| 503が続く | プロセスの再起動ループ(環境変数の不足が多い) | プラットフォームのログ。同じ環境変数で手元のコンテナを起動する |
| 長いツール呼び出しで504 | プロキシやプラットフォームのリクエストタイムアウト | 呼び出しを短くするか、進捗通知やタスクを使う |
| 応答の途中で接続が切れる | プロキシがSSEをバッファしたり切断したりしている | JSON応答にするか、text/event-stream のバッファリングを止める |
| 413 | リクエスト本文がサイズ上限を超えた | ペイロードを小さくするか、上限を上げる |
| 429 | IP、キー、プランのレート制限 | 間隔を空けて再送し、どの層が返したかを確認する |
2026-07-28では、応答ストリームが切れるとそのリクエストは失われます。changelogには、クライアントは新しいリクエストIDで新しいリクエストとして送り直すのがMUSTとあります。SSEを切るプロキシがあると、ストリームの再開ではなく再送が起きます。
9. curlで5段階に切り分ける
上から順に実行します。1段階ごとに2章の層を1つずつ除外でき、最初に失敗した段階に問題があります。
URL=https://mcp.example.com/mcp # クライアント設定と完全に同じURL
H=(-H 'Content-Type: application/json'
-H 'Accept: application/json, text/event-stream'
-H 'MCP-Protocol-Version: 2026-07-28'
-H "Authorization: Bearer $MCP_TOKEN")
META='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"diag","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}'
# 1. ネットワークとTLS:何らかのHTTPステータスが返るか(ここでは405でもよい)
curl -sv -o /dev/null "$URL" 2>&1 | grep -E '^< HTTP|SSL|Connected|refused'
# 2. プロトコル:server/discoverが200とsupportedVersionsを返すか
curl -s -i "$URL" "${H[@]}" -H 'Mcp-Method: server/discover' \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{$META}}"
# 3. 認可:Authorizationを外して2を再実行。401とWWW-Authenticateが返るはず
# 4. ツール一覧:Mcp-Method: tools/list で tools/list
# 5. 実際の呼び出し:Mcp-Method: tools/call と Mcp-Name: <ツール名> で tools/call
curlでは成功するのにクライアントだけ失敗するなら、違いはクライアントが送っている内容にあります。URL(末尾スラッシュ、パス)、認証ヘッダー、ブラウザ型かどうか(CORS)を比べてください。curlでも同じように失敗するなら、問題はサーバーかプラットフォームにあり、4章の表でどちらか分かります。
10. チェックリスト
- [ ] クライアントのURLがエンドポイントと完全に一致している(
/mcpを含み、末尾スラッシュなし) - [ ] 2026-07-28のヘッダーを付けたcurlで
server/discoverが200になる - [ ] サーバーが公開ホスト名の
Hostを受け付け(421にならない)、Originを自分か前段で検証している - [ ] クライアントが
Accept: application/json, text/event-streamを送っている - [ ] プロキシが
MCP-Protocol-Version、Mcp-Method、Mcp-Name、Mcp-Param-*をそのまま転送している - [ ] ブラウザ型クライアント向けに、
OPTIONSがMCPのヘッダーを許可して200を返し、www-authenticateを公開している - [ ] 401に
resource_metadata付きのWWW-Authenticateがあるか、well-knownのURIを置いている - [ ] トークンをクエリ文字列ではなく
Authorizationヘッダーで送っている - [ ] 監視やスクリプトが
pingや単純なGETではなくserver/discoverを使っている - [ ] 使い続ける旧クライアントを、更新後のサーバーで試した
- [ ] プラットフォームのタイムアウトが、最も遅いツール呼び出しとコールドスタートより長い
11. NodeFlareならこう解決できる
NodeFlareは、GitHubリポジトリのMCPサーバー(stdio専用のものを含む)を、認証付きのHTTPSエンドポイントとしてデプロイするMCP Hostingサービスです。この記事で取り上げた接続エラーには、次のように対応しています。
| この記事の課題 | NodeFlareでの対応 |
|---|---|
| パスの推測による404、末尾スラッシュによる307 | サーバーごとにURLが1つに決まっています(https://<your-server>.nodeflare.tech/mcp)。MCPのパスは既定で /mcp で、ビルド設定で変えられます |
| プロセスが待ち受けていないことによる502・503 | デプロイのたびに本物のMCP initialize を送って確認し(バックオフ付きで最大8回)、Verified・Broken・Inconclusiveに分類します。「接続を一度も受け付けなかった」場合は、PORT を使って 0.0.0.0 で待ち受けるようヒントが出ます |
| 401とOAuthの自動検出の失敗 | サーバーのコードを変えずに、Bearer APIキー(mcp_*)が使えます。プロキシがRFC 8414とRFC 9728に沿ったメタデータを返すので、仕様に沿ったクライアントは認可サーバーを自動で見つけられます。誤ったキーを繰り返し送るIPは10分間ロックされます |
| 原因の分からない403・スコープエラー | tools:call:get_weather のようなスコープを、リクエストがサーバーに届く前に検査し、拒否は scope_denied としてログに残します |
| 旧クライアントや旧URL | Streamable HTTPと、従来の2024-11-05のHTTP+SSEの両方に対応しています |
| curlでは200なのにクライアントでは失敗する | リクエストログに mcp_method、tool_name、http_status、outcome、duration_ms、user_agent、client_ip、error_message が残るので、クライアントのリクエストと自分のリクエストを比べられます(保存期間はFreeで7日、ProとTeamで30日) |
| 429・402・IP制限 | IPごとのレート制限はログに rate_limited として残ります。有料プランでは月の支出上限に達すると402を返します。ProのIP許可リストは認証より前に適用され、リストが空だとすべて拒否します |
| アイドル後の最初の呼び出しのタイムアウト | アイドル状態が数分続くとスナップショットを取って停止し、次のリクエストで1秒未満に復元します |
料金:Freeは¥0で、MCPサーバー1つと月30 GB時間のコンピュートが使えます。Proは月¥2,980で、サーバー数無制限、300 GB時間込みで、自動TLS付きの独自ドメインも使えます。
最小の始め方:
- nodeflare.techにGitHubでログインし、MCPサーバーのリポジトリを選ぶ。
- デプロイして、ステータスがVerifiedになるのを待つ。
https://<your-server>.nodeflare.tech/mcpとmcp_*のAPIキーをクライアントに設定し、失敗したらリクエストログを見る。
1サーバーまで無料で試せます → nodeflare.tech
12. よくある質問(FAQ)
MCPサーバーが手元では動くのにデプロイすると動かないのはなぜ?
よくある原因は3つです。待ち受けアドレスが 127.0.0.1 でプラットフォームが502を返す、Host の検証でPython SDKの既定設定がlocalhostしか許可せずプロキシの後ろで421になる、クライアントのURLのパスや末尾スラッシュが違う、のいずれかです。公開URLにcurlで server/discover を送れば、どれなのかが分かります。
MCPサーバーの「421 Invalid Host header」とは?
サーバーのDNSリバインディング対策が Host ヘッダーを拒否したという意味です。MCP Python SDK 2.3.0の streamable_http_app() は、既定の設定だと 127.0.0.1、localhost、[::1] しか許可しないため、公開ホスト名へのリクエストは421になります。TransportSecuritySettings の allowed_hosts にホスト名を追加してください。
MCPサーバーに接続すると406 Not Acceptableになるのはなぜ?
Accept ヘッダーに、サーバーが必要とする応答形式が含まれていないためです。2026-07-28仕様では、クライアントは application/json と text/event-stream の両方を送る必要があります。既定のSSE応答のPython SDKサーバーは、Accept: application/json だけのリクエストに406を返しました。
MCPのエラー -32020 とは?
2026-07-28仕様のHeaderMismatchです。MCP-Protocol-Version、Mcp-Method、Mcp-Name が欠けている、形式が誤っている、または本文と一致しないときに、サーバーがHTTP 400とともに返します。2026-07-28のchangelogで -32001 から番号が変わりました。
MCPのエラー -32022 とは?
UnsupportedProtocolVersionです。要求されたプロトコルバージョンにサーバーが対応していないとき、HTTP 400と data.supported の一覧付きで返ります。クライアントはその一覧から版を選んで再送します。それができない場合は、クライアントかサーバーのSDKを更新します。
MCPサーバーが405 Method Not Allowedを返すのはなぜ?
GET(またはDELETE)で送ったためです。2026-07-28のサーバーは、MCPエンドポイントへのPOSTしか受け付けません。ブラウザでURLを開いた場合、旧SSEのクライアント、GETで確認する死活監視は、どれも405になります。ブラウザ型クライアントでは、OPTIONS のプリフライトへの405がCORSエラーとして表示されます。
MCPサーバーで「Missing session ID」と出るのはなぜ?
旧来のセッション前提のリクエストが、initialize を送らず、2026-07-28のヘッダーも付けずにサーバーに届いたためです。セッション時代のサーバーやSDKの旧形式の処理では、initialize と Mcp-Session-Id が必要です。新しいクライアントは、毎回 MCP-Protocol-Version: 2026-07-28 と _meta を付けるので、このエラーは出ません。
ブラウザで動くMCPクライアントがCORSエラーになるのはなぜ?
ブラウザが送る OPTIONS のプリフライトが拒否されたか、Access-Control-* ヘッダーのない応答が返ったためです。検証したPython SDKのサーバーは、プリフライトに405を返しました。POST、OPTIONS と、content-type、accept、authorization、mcp-protocol-version、mcp-method、mcp-name の各ヘッダーを許可し、www-authenticate を公開するCORSミドルウェアを追加してください。
APIキーを設定したのにリモートMCPサーバーが401を返すのはなぜ?
よくある原因は、トークンを Authorization ヘッダーではなくクエリ文字列で送っている、Bearer の接頭辞がない、トークンが期限切れ、別のサーバー向けに発行されたトークン(audience違い)を使っている、のいずれかです。2026-07-28仕様では無効・期限切れのトークンに401を返すのが必須で、応答の WWW-Authenticate ヘッダーに使うべき認可サーバーが示されます。
MCPの接続確認にpingはまだ使える?
使えません。2026-07-28仕様で ping は削除され、2026-07-28のサーバーは404と -32601(Method not found)を返します。代わりに server/discover を使ってください。2026-07-28のサーバーはすべて実装する必要があり、セッションも不要です。
MCPエンドポイントのURLは末尾にスラッシュを付けるべき?
付けないでください。サーバーが提供しているパス(通常は /mcp)を正確に使います。検証では /mcp/ が /mcp への307リダイレクトになりました。POSTのリダイレクトをたどらないクライアントもあり、TLSプロキシが X-Forwarded-Proto を渡さない場合は、リダイレクト先が http:// になることもあります。
まとめ
リモートMCPの接続エラーは、どの層が返したかが分かれば予測できます。MCP Python SDK 2.3.0での検証では、Host の誤りで421、Accept の不足で406、MCPヘッダーの欠落や食い違いで -32020 付きの400、非対応のバージョンで -32022、削除されたメソッドで -32601 付きの404、GETで405、末尾スラッシュで307が返りました。ブラウザのプリフライトへの405はCORSエラーとして表示されました。調査は、クライアントと同じURLに2026-07-28のヘッダーを付けたcurlを送るところから始め、生のステータスと本文を読み、拒否した層を直してください。
参考資料
- MCP Specification 2026-07-28: Streamable HTTP transport
- MCP Specification 2026-07-28: Authorization
- MCP Specification 2026-07-28: Versioning
- MCP Specification 2026-07-28: Changelog
- MCP Python SDK(GitHub)
- RFC 9728: OAuth 2.0 Protected Resource Metadata
- RFC 8414: OAuth 2.0 Authorization Server Metadata
- Starlette: CORSMiddleware
- MDN: プリフライトリクエスト
- Uvicorn: settings(プロキシヘッダー)
