Claude Media
Insomnia MCPクライアントの使い方 — 自作MCPサーバーを検証する
MCPClaude Codeチュートリアル

Insomnia MCPクライアントの使い方 — 自作MCPサーバーを検証する

InsomniaのMCPクライアント機能で外部MCPサーバーに接続し、ツール・プロンプト・リソースを呼び出す手順と、認証の止まり方の見分け方、Claude Code側の設定との対応を扱います。

読了目安 約14分

Insomniaには、HTTPで公開されたMCPサーバーに接続してツール・プロンプト・リソースを呼び出せる「MCPクライアント」機能があります。自作のMCPサーバーをClaude Codeにつなぐ前に、サーバー側の不具合を先に切り分ける用途に向いています。

InsomniaのMCPクライアントが対象にするのはHTTPのエンドポイントで、公式ページは標準入出力(stdio)での接続手順を載せていません。

MCPサーバー自体の作り方はMCPサーバー自作ガイド、Claude Code側の接続構文はClaude Code MCP設定ガイド、MCPの概念はMCPクライアント概念ガイドが扱っています。

Insomniaで検証できるサーバーの条件

MCPの仕様が定める通信路(トランスポート)はstdioとStreamable HTTPの2種類です。InsomniaのMCPクライアントが対象にするのは後者で、公式ページはサーバーを「HTTP JSON-RPCのエンドポイント」と説明しています。

一方、Claude Codeのclaude mcp addはstdio・http・sseを選べて、--transportを省くとstdioとして登録されます。同じサーバーでも、起動方法によってInsomniaで手順どおりに試せるかどうかが変わります。

  • npxなどでローカル起動するstdioサーバー: Insomniaの公式ページに接続手順がありません。Claude Code側のclaude mcp add my-server -- <起動コマンド>で検証します
  • https://…/mcpのようなURLで公開されたサーバー: Insomniaで試せます

接続して発見できるのはツール(実行できるサーバー側の関数)、プロンプト(再利用できるテンプレート)、リソース(構造化された文脈データ)の3種類です。MCPクライアントはプロジェクト単位のリソースで、1つのワークスペースに複数作れます。保存先はGit・クラウド・ローカルのいずれかのプロジェクトで、他のリソースと同じようにバージョン管理・同期・共有の対象です。

クライアントを作成して接続する

手順

接続までの4手順

  1. 1

    MCP Clientsを作る

    左ペインの「MCP Clients」をクリックし、「Name」欄に名前を入れて「Create」を押します。

  2. 2

    サーバーのURLを入れる

    「MCP Server URL」欄にエンドポイントの完全なURLを入力します。公式ページの例はhttps://mcp.deepwiki.com/mcpです。

  3. 3

    Connectで接続する

    「Connect」をクリックします。認証が必要なサーバーなら、MCP Auth Flowに従ってサインインするかトークンを入れます。

  4. 4

    発見結果を確かめる

    左ペインに、ツール・プロンプト・リソースが並べば接続できています。

自作サーバーの確認では、ここでツールが期待どおり並ぶかが最初の関門です。並ばないときは、後述の「Console」タブで生のリクエストとレスポンスを見ます。

各ペインの役割

接続後の画面には、操作の実行と結果の確認に使うペインが並びます。

ペイン役割
Params役割選択した操作の入力パラメータを編集する。欄はサーバーのスキーマが示すパラメータに対応する
Auth役割認証情報を設定する
Headers(リクエスト側)役割カスタムヘッダーの追加・上書き
Roots役割接続先サーバーのエンドポイントやツールの一覧。選ぶとParamsタブに読み込まれる
Events役割発見の更新や認証状態の変化などのサーバーイベント
Notifications役割サーバーやInsomniaランタイムからの情報・エラー(同期成功やOAuthエラーなど)
Headers(レスポンス側)役割サーバーが返したヘッダー。ステータスやコンテンツタイプの確認に使う
Console役割生のリクエスト・レスポンスのログ

Rootsタブの名前には注意が要ります。MCPの仕様でいうRootsは、クライアントがサーバーに「作業対象のディレクトリやファイル」を知らせる機能です。Insomniaの公式ページはこのタブを、サーバーが公開するエンドポイントやツールの一覧として説明しています。同じ名前でも指すものが違うので、仕様のRootsの検証をこのタブでする、とは考えないほうが安全です。

仕様側のRootsは、2026-07-28版のプロトコルで非推奨になりました。新しい実装には採用しないよう求められ、ディレクトリはツールのパラメータやリソースURIで渡す形が案内されています。Claude Codeはroots/listに応答し、返すのは起動ディレクトリと--add-dirなどで足した作業ディレクトリです。

認証が止まる場所を見分ける

認証つきのサーバーでは、Insomniaは次のように動きます。サーバーが401 Unauthorizedと有効なメタデータを返すと、対応するOAuth認可サーバーを自動で見つけます。認証方式が「OAuth 2.0 > MCP Auth Flow」ならそのままトークンを要求し、別の方式を選んでいれば切り替えを提案します。

見つかった認可サーバーが使えるかどうかで、進め方が2通りに分かれます。

くらべる

認可サーバーの状況別の進め方

自動で進む

メタデータあり・登録に対応

MCP Auth Flowがそのまま走ります。Insomniaは各リクエストとレスポンスを表示するので、どの段で失敗したかも追えます。

手動で補う

DCRに非対応

Personal Access Token(PAT)を使うか、自分でOAuthアプリを登録してClient IDとSecretをInsomniaに入力します。PATの例として公式ページはGitHub Copilot MCPサーバーを挙げています。

PATで通すなら、「Auth」タブで「Bearer Token」を選び、「Token」欄にPATを入れます。OAuthのフローは経由しません。OAuth 2.0の選択肢に「MCP Auth Flow」が出ないのは、サーバーのメタデータに有効な認可エンドポイントが無いときで、その場合もPATかBasic Authを使います。

仕様の変化とInsomniaの説明のずれ

Insomniaのヘルプが認可サーバー側の要件として挙げるのはDynamic Client Registration(DCR、クライアントの動的登録)だけです。MCPの仕様の現行ドラフトでは、DCRは後方互換のために残された扱いです。クライアントと認可サーバーが対応すべきとされているのは、OAuth Client ID Metadata Documents(CIMD)です。

MCPサーバーはProtected Resource Metadata(RFC 9728)の実装が必須で、401のWWW-AuthenticateヘッダーにそのメタデータのURLを載せます。クライアントはこの流れで認可サーバーを見つけます。

Claude Codeのドキュメントには、CIMDを使うサーバーも自動で見つける、と書かれています。DCRに非対応のサーバーに当たると、Claude Codeは「Incompatible auth server: does not support dynamic client registration」のようなエラーを出し、事前登録の資格情報を求めます。

Insomniaのヘルプに載っているのはDCRまでなので、CIMDで登録を受け付ける認可サーバーの場合、Insomniaの説明だけでは対応方式が読み取れません。片方のツールで通らなかったときは、もう片方でも試すと原因が絞れます。

Elicitation — サーバーが追加情報を求める仕組み

Elicitationは、リクエストの処理中にサーバーがクライアントへ追加の入力を求める機能です。Insomniaはサーバーが定義したフィールドをもとに、レスポンスペインへフォームを出します。入力した値はElicitationレスポンスとしてサーバーに返り、サーバーは元の処理を再開します。

Claude Codeでも同じ種類のリクエストが動きます。設定は不要で、サーバーが求めると自動でダイアログが開きます。形式は2通りです。

  • フォーム形式: サーバーが定義したフィールドをダイアログで埋める
  • URL形式: ブラウザーでリンクを開くかどうかを尋ねる。サインインのように、ターミナルの外で終わる流れに使われる

ダイアログを出さずに自動応答させたいときは、Elicitationフックがあります。

Sampling — サーバーがモデルの応答を求める仕組み

Samplingは、MCPサーバーがInsomnia側のAI統合を使って、モデルの応答を生成させる仕組みです。サーバーが送るのは次のメソッドです。

{
  "method": "sampling/createMessage"
}

Insomniaの流れは、人が2回確認を挟む形です。

手順

Samplingの往復

  1. 1

    サーバーがリクエストを送る

    サーバーがsampling/createMessageを送ると、Insomniaがレスポンスペインに内容を表示します。

  2. 2

    リクエストを確認して承認する

    利用者は生成の前に、内容を確認して修正できます。承認すると、Insomnia AIが使っているモデルへ転送されます。

  3. 3

    応答を確認して返す

    モデルの出力も表示され、修正してから承認できます。承認した結果がサーバーに返ります。

対応するサーバーなら、この往復を複数ターン続けられます。Claude Codeの公式MCPページにはElicitationの節がある一方で、samplingの節はありません。samplingを使う自作サーバーの動作は、Insomniaのレスポンスペインで承認の往復を見ながら試せます。

トークン上限を設定する

Samplingで呼ばれるモデルは、既定では1リクエストでモデルの上限までトークンを使えます。コストを抑えるには、次の順に上限を設定します。

  1. 「Preferences」>「AI Settings」>「Activate an LLM」を開く
  2. 「LLM URL」を選び、https://api.openai.com/v1のようなプロバイダーのURLか、自前のURLを入れる
  3. 「API Token」欄にトークンを入れる
  4. 「Advanced Options」をクリックし、「Max Tokens」欄に1リクエストあたりの上限を入れる

Claude Codeへつなぐ前に確認すること

自作サーバーをClaude Codeのmcp addで接続する前にInsomniaで検証しておくと、Claude Code側の失敗表示だけでは切り分けにくい問題を先に見つけられます。Claude Code側の状態は、claude mcp listが✔ Connected・! Needs authentication・✘ Failed to connectのいずれかで示します。

下の表は、Insomniaで見る場所と、Claude Code側で対応する状態や設定の対応表です。

確認項目Insomniaで見る場所Claude Code側の対応
サーバーがHTTP JSON-RPCで応答するかInsomniaで見る場所Console(生のリクエスト・レスポンス)Claude Code側の対応✘ Failed to connectの原因探し
ツール・プロンプト・リソースが期待どおり並ぶかInsomniaで見る場所左ペインの発見結果Claude Code側の対応/mcpで見える一覧との突き合わせ
401のあとOAuthメタデータを返すかInsomniaで見る場所MCP Auth Flow(Authタブ)Claude Code側の対応! Needs authenticationの解消は/mcpかclaude mcp login <name>
ヘッダーやステータスが想定どおりかInsomniaで見る場所Headers(レスポンス側)Claude Code側の対応--headerで渡すヘッダーの検証

Claude Codeでは、headersやheadersHelperでAuthorizationヘッダーを設定したサーバーが401か403を返しても、OAuthへは切り替わりません。接続失敗として扱われます。Insomniaで同じ401に当たったときは、サーバーがメタデータを返す実装を持つかを見ます。ヘッダーの資格情報の誤りなのか、メタデータの無いサーバーなのかを分けられます。

実際のオプションをclaude mcp add --helpで見ると、OAuthやヘッダーに関わるものは次のとおりです(v2.1.289の出力から抜粋)。

claude mcp add --help
Options:
  --callback-port <port>       Fixed port for OAuth callback (for servers
                               requiring pre-registered redirect URIs)
  --client-id <clientId>       OAuth client ID for HTTP/SSE servers
  --client-secret              Prompt for OAuth client secret (or set
                               MCP_CLIENT_SECRET env var)
  -H, --header <header...>     Set headers for HTTP/SSE servers
  -t, --transport <transport>  Transport type (stdio, sse, http). Defaults to
                               stdio if not specified.

InsomniaでOAuthアプリを自分で登録し、Client IDとSecretを入れて通ったサーバーは、同じ値を--client-idと--client-secretで渡せます。リダイレクトURIを事前登録するサーバーでは、--callback-portでポートを固定し、http://localhost:PORT/callbackの形で登録します。クライアントシークレットを設定できるのは、サーバーを追加するときだけです。

環境変数の扱いにも罠があります。リモートサーバーのurlやheadersにBearer ${ANTHROPIC_AUTH_TOKEN}のように書いても、Claude Codeは自身の認証情報を空として読みます。サーバーにはBearer だけが届き、401で拒否されます。Insomniaで固定のトークンを入れると通るのにClaude Codeでだけ401になるときは、この点が候補になります。

MCP Inspectorとの違い

自作MCPサーバーの動作確認という用途ではMCP Inspectorも選択肢になります。両者の違いは、土台にあるものです。InsomniaのMCPクライアントは、Git・クラウド・ローカルのプロジェクトで管理できるAPIクライアントの上にMCPの機能が乗っています。REST APIの開発と同じプロジェクトの中で、MCPサーバーも検証したいチームに向く構成です。

よくあるつまずき

401 Unauthorizedが出て発見が止まる

多くのMCPサーバーは、クライアントが先に認可サーバーを見つけることを前提にしています。サーバーが401とメタデータを返し、クライアントがそれをたどってOAuthのエンドポイントを得る流れです。DCRに対応しない認可サーバーでは、事前登録済みのクライアントかPATを使います。

アップグレード後にMCPクライアントが表示されない

Insomnia 12.3より前のバージョンで開いたGit・クラウドプロジェクトにMCPクライアントのファイルが含まれていると、アップグレード後も表示されないことがあります。プロジェクトを再クローンすると、リソースが読み込まれます。

サーバー側の操作一覧を更新したい

「MCP Servers」の左ペインで「Resync」をクリックすると、ツール・プロンプト・リソースを再取得できます。

実行が長引くリクエストを止めたい

「Events」タブで、実行中のリクエストの横にあるキャンセルアイコンをクリックします。現在のMCPタスクが終了し、操作がアプリに戻ります。

認証をやり直したい

「Authentication」タブでサーバーとの接続を解除し、現在のアクセストークンの値を削除してから、再接続するかリクエストを送ります。MCP Auth Flowが再始動するのは、サーバーが401 Unauthorizedを返したときだけです。個々の呼び出しを部分的にやり直すことはできず、フロー全体をやり直す形になります。

接続できない、何も発見されない

サーバーがHTTP JSON-RPCトランスポートに対応しているか、有効なMCPエンドポイントを公開してオンラインかを確かめます。応答しない状態でも、Insomniaは次回の同期が成功するまで、キャッシュしたリソースを表示し続けます。表示が出ているからといって、サーバーが生きているとは限りません。

まとめ

自作サーバーがhttps://のURLで公開されているなら、Insomniaで認証・発見・呼び出しを通してからClaude Codeへ登録すると、原因がサーバー側か登録設定側かを分けやすくなります。stdioで起動するサーバーはInsomniaの公式ページに手順がないため、Claude Code側のclaude mcp addで直接確かめます。

この記事を共有:XはてブLinkedIn

関連する記事

MCP をもっと見る →