Instana MCPサーバーをClaudeにつなぎ、障害調査を会話で進める

IBM InstanaのMCPサーバー(mcp-instana)は、Instana REST APIの前に立つ橋渡し役です。Claudeが出した質問をInstanaのAPI呼び出しに変換し、結果を整形して返します。アラートの確認、アプリケーションのメトリクス、インフラの状態、イベントの検索を、監視画面を開かずに会話の中で進められます。

つなぎ方は2通りです。Claude DesktopやClaude CodeからローカルのMCPサーバーをstdioで起動する方法と、Streamable HTTPで別プロセスに立てたサーバーへmcp-remote経由で入る方法があります。この記事では前者を主軸に、認証ヘッダー、ツールの絞り込み、障害調査での質問の組み立て方を説明します。

Instana MCPサーバーとは何か

mcp-instanaは、Instanaの監視データをMCPクライアントから引くためのサーバーです。クライアントとして、Claude Desktop、Cursor、GitHub Copilot、Gemini CLIなどが並んでいます。Claude Desktopはstreamable HTTPとstdioの両方が対応と書かれています。

Claudeのコネクタ一覧には「MCP Instana Server」として、Anthropic verifiedの表示付きで掲載されています。提供元は「MCP Instana Team」、追加は2025年10月と記されています。一覧ページには「Add to Claude」ボタンがあり、そこから追加できます。

一覧ページの説明は一文程度です。接続先URLや認証方式、必要な権限は載っていません。社内のInstanaに接続する場合は、次に示すリポジトリの手順で自前のサーバーを用意するほうが、認証と公開範囲を自分で決められます。

動作の流れは次のとおりです。

READMEの例は「アプリケーションrobot-shopの最新アラートを見せて」という質問です。アプリケーション名を添えて聞くと、対象が絞れます。

事前に用意するもの

動作の前提は次の3点です。

• Python 3.10以上
• pip 21.3以上(PyPIからの導入に必要)
• uv 0.11.6以上(リポジトリからの開発用導入にのみ必要)

あわせてInstanaのベースURL(https://your-instance.instana.ioの形)と、Instanaで発行したAPIトークンが必要です。トークンにはMCPツールを呼べる権限が要ります。権限が足りないと、Claudeに質問しても取得系のツールが失敗します。トークンの権限は、調べたい範囲だけに絞って発行するのが前提になります。

PyPIからの導入は1行です。

pip install mcp-instana
mcp-instana --list-tools

--list-toolsはツールのカテゴリを一覧表示して終了します。このあと--toolsに渡すカテゴリ名は、ここで確認してから決めます。

Claude Desktopにstdioでつなぐ

stdioモードでは、MCPクライアントがサーバーを子プロセスとして起動します。認証は環境変数で渡します。Claude Desktopの設定に書くMCPサーバー定義は、次の形になります。

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio", "--tools", "infra,events"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

これはREADMEのツール絞り込みの例に沿った形です。--tools infra,eventsの部分で、見せるカテゴリをインフラとイベントに限っています。--transportを省くとstdioが既定です。

設定を保存して再起動すると、Claude Desktopのツール一覧にInstanaのツールが並びます。最初の質問は、書き込みを伴わない軽いものから始めると挙動を確かめやすくなります。

Instanaで、アプリケーション robot-shop の直近のアラートを見せて

Streamable HTTPで共有サーバーとして使う

チームで1台のMCPサーバーを共有したい場合は、Streamable HTTPモードを使います。起動はこうなります。

mcp-instana --transport streamable-http --tools app,events

待ち受けは既定でポート8080、MCPのエンドポイントはhttp://0.0.0.0:8080/mcp/です。ヘルスチェック用の管理ポートは既定で8601です。--portと--admin-portで変えられ、環境変数PORTとADMIN_PORTでも指定できます。稼働確認はcurlで足ります。

curl http://0.0.0.0:8080/mcp/

HTTPモードでは、環境変数でなくHTTPヘッダーで認証情報を渡すのが決まりです。サーバー側にトークンを置かず、リクエストごとに別の認証情報を使えます。Claude Desktopからはmcp-remoteを挟んでヘッダーを付けます。

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http",
        "--header",
        "instana-base-url: https://your-instana-instance.instana.io",
        "--header",
        "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

--allow-httpは平文HTTPを許す指定です。READMEの例は手元のローカルサーバーが前提なので、ネットワーク越しに共有するなら、前段にTLS終端を置いてhttpsで公開する構成を別に考える必要があります。

認証は3方式、優先順位あり

ヘッダー認証には3つの方式があります。

複数の方式が同時に届いたときは、JWT(CSRFトークン付き)、セッショントークン、APIトークン、環境変数INSTANA_API_TOKENの順に優先されます。有効な認証がないリクエストは失敗します。個人で調査に使うだけなら、APIトークンの方式で足ります。

本番と検証の2環境をまとめて扱う

サーバー定義を2つ並べると、環境ごとにInstanaを使い分けられます。READMEの例は「Instana MCP Server1」「Instana MCP Server2」の名前でベースURLとトークンを分けています。質問にはサーバー名か環境名を書きます。書かないと、設定の先頭に定義したサーバーが既定で選ばれます。

Instana MCP Server2 の環境で、イベントを直近のものから見せて

接続先がダウンしていても自動の切り替えはありません。Instana側のAPIエラーがそのまま返ります。

ツールの絞り込みが、書き込み系を避ける実質的な手段になる

ここが運用上の分かれ目です。READMEのツール表には、読み取り専用でないものが混じっています。

リリースの削除やメンテナンスウィンドウの作成は、障害調査の最中に会話の勢いで実行されると困る操作です。manage_*は「ルーター」型のツールで、読み取りも書き込みも1つのツール名の中にあります。そのためClaude Code側のパーミッションでツール名単位に拒否すると、読み取りも一緒に塞がります。

細かく分けたいときは、サーバー起動時のカテゴリ指定が確実です。調査だけなら次のように、見せるカテゴリを調査向けに限ります。

"args": ["--transport", "stdio", "--tools", "app,infra,events"]

逆に、特定のカテゴリだけ外すなら--omit-toolsです。--toolsで絞った集合から、さらに--omit-toolsで引くこともできます。HTTPモードなら、サーバーを再起動せずに、クライアントごとにselect-toolsとomit-toolsのヘッダーで絞れます。ただしこれらのヘッダーはstdioモードでは効きません。

カテゴリ名はREADMEの中で表記が揺れています。ある箇所はmaintenance、別の箇所はmaintenance_windows、ダッシュボードはsettingsとcustom_dashboardsの両方が出てきます。未知のカテゴリ名は警告ログに出るだけで、黙って無視されます。名前を間違えると絞り込んだつもりで全部出ている、ということになりかねないので、mcp-instana --list-toolsの出力を正としてください。

Claude Codeから使う

Claude Codeではclaude mcp addで登録します。stdioサーバーは、--の前にClaude側のオプション、後ろにサーバーを起動するコマンドを書きます。後ろの引数はそのままサーバーに渡されます。

claude mcp add --transport stdio \
  --env INSTANA_BASE_URL=https://your-instance.instana.io \
  --env INSTANA_API_TOKEN=your_instana_api_token \
  instana -- mcp-instana --transport stdio --tools app,infra,events

Claude Desktopの設定に書くJSONを、Claude Codeに移すだけならclaude mcp add-jsonも使えます。登録後はclaude mcp get instanaで接続状況を確かめられます。Claude Codeの/mcpでも状態が見えます。

トークンをコマンド履歴に残したくなければ、--scope userで自分の環境にだけ登録するか、プロジェクトの.mcp.jsonには環境変数の参照だけを書いて、値はシェル側に置く運用が向きます。チームで.mcp.jsonを共有する場合、APIトークンの実値をコミットしないことが最低条件です。MCPサーバーの設定全般はClaude CodeのMCPサーバー設定ガイドにまとめています。

Claude Codeの権限ルールは、MCPツールをmcp__<サーバー名>__<ツール名>で指します。サーバー名をinstanaで登録した場合、manage_eventsはmcp__instana__manage_eventsになります。サーバー全体ならmcp__instana__*と書けます。allowルールのグロブは、mcp__<server>__の接頭辞より後ろにだけ使えます。

{
  "permissions": {
    "allow": ["mcp__instana__manage_events", "mcp__instana__manage_applications"],
    "deny": ["mcp__instana__manage_releases", "mcp__instana__manage_maintenance_windows"]
  }
}

先ほどの理由で、manage_applicationsには設定変更も含まれます。allowに入れると、その中の書き込みも承認なしで通る可能性がある点には注意が要ります。書き込みを避けたいカテゴリは、権限ルールだけに頼らず--toolsで外すのが安全側です。

障害調査で試す質問の組み立て

ツールが繋がったら、調査の順番を決めて質問します。一例です。

1. 「今アクティブなイベントとアラートを、サービス名つきで一覧にして」
2. 「robot-shopのレイテンシとエラー率を直近1時間で出して」
3. 「同じ時間帯のインフラ側のイベントを出して」
4. 「ここまでの結果を時系列でまとめて、疑わしい順に3つ挙げて」

最後の「疑わしい順」は、Claudeの推論です。Instanaが返した事実とは分けて読んでください。Claudeは取得した数値の並びから仮説を立てられても、原因を確定できるわけではありません。確認したい仮説ごとに、元のトレースやダッシュボードを開いて裏取りする使い方が現実的です。

つまずきやすい点

READMEが挙げている起動時の問題と、設定の勘どころです。

SSL証明書のエラー。Instanaへの通信は既定で証明書を検証します。自己署名や社内CAの環境では、--verify-ssl false、環境変数INSTANA_SSL_VERIFY=false、またはconfig.yamlのsslVerify: falseで無効化できます。無効化は通信の安全性を下げるので、社内CAならINSTANA_CA_BUNDLEでCAバンドルを指定するほうが穏当です。起動ログに、実際に有効になった検証設定が出ます。

ポートの競合。8080が使用中なら、--port 9000のように別ポートで起動します。

依存関係の不足。開発用導入ではuv syncで依存を揃えます。

待ち時間が長い。各APIコールには時間切れがあり、既定は180秒です。INSTANA_API_TIMEOUTに秒数を入れると短縮できます。正の整数以外の値は無視され、既定値に戻ります。

カタログ応答のキャッシュ。メトリクスやタグなどのカタログ系は、サーバープロセス内に30分(既定)保持されます。新しい連携を入れた直後に、まだカタログに現れないときはINSTANA_CACHE_TTLを短くするか、INSTANA_CACHE_ENABLED=falseで切ります。HTTPモードではリクエストごとにinstana-cache-enabled、instana-cache-ttlヘッダーで上書きできます。

他の監視ツールの連携記事との違い

同じ「障害対応をClaudeに任せる」でも、接続の形は製品で違います。Better Stackはリモートのホスト型MCPサーバーにブラウザでサインインする形で、ClaudeとBetter Stackの連携で扱っています。AWSは認証方式の選択が論点で、ClaudeとAWS MCPサーバーの連携に書きました。Grafana側のCLI操作はClaude CodeのGrafana Assistantプラグインの話です。

Instanaの場合は、サーバーを自分で動かし、Instanaの認証情報を自分で渡す構成が中心です。手間は増えますが、どのカテゴリを見せるか、どのトークンで繋ぐかを自分の側で決められます。

まとめ

Instana MCPサーバーは、pip install mcp-instanaと環境変数2つで、Claude Desktopからすぐ動きます。複数人で使うならStreamable HTTPとヘッダー認証に進みます。実運用で効くのは、--toolsによるカテゴリの絞り込みです。リリースやメンテナンスウィンドウの書き換えを調査用のセッションから外しておけば、Claudeに任せる範囲が読み取りに寄ります。