Skip to content

MCP Server for Instana

概要とメリット

  • MCP (Model Context Protocol) Serverは、AI開発ツール（Claude Desktop、Cursor、IBM watsonx Code Assistantなど）とInstanaを統合し、自然言語でInstanaのデータにアクセスできる機能です。
  • 主なメリット
  • AI開発ツールから直接Instanaのメトリクス、トレース、イベントを照会できます
  • 自然言語でのクエリにより、複雑なAPIコールを意識せずにデータを取得できます
  • 開発ワークフロー内でシームレスに可観測性データを活用できます
  • インシデント調査やパフォーマンス分析を効率化できます
  • IBM製品との統合により、エンタープライズ環境での活用が容易です

公式ドキュメントのリンク

基本的な設定手順は公式ドキュメントを参照してください。最新の設定例や詳細な情報はGitHubリポジトリで確認できます。

前提条件

以下の準備が整っていることを確認してください。

  • Node.js: バージョン18以上がインストールされていること
  • node --versionで確認できます
  • Instana APIトークン: 適切な権限を持つAPIトークンが作成されていること
  • 必須権限: Configuration of applications、Access audit log、Access Analyze（読み取り）
  • AI開発ツール: 以下のいずれかがインストールされていること
  • Claude Desktop
  • Cursor
  • IBM watsonx Code Assistant (Bob)
  • ネットワーク: Instanaバックエンドへのアクセスが可能であること
  • プロキシ環境の場合は、プロキシ設定が必要です

設定例

以下の設定例は記事作成時点のものです。最新の設定方法は公式GitHubリポジトリを参照してください。

各AI開発ツールでの設定

Claude Desktopの場合:

設定ファイルの場所: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "mcpServers": {
    "instana": {
      "command": "npx",
      "args": ["-y", "@instana/mcp-server-instana"],
      "env": {
        "INSTANA_BASE_URL": "https://<your-tenant>.instana.io",
        "INSTANA_API_TOKEN": "<your-api-token>"
      }
    }
  }
}

Cursorの場合:

設定ファイルの場所: - macOS/Linux: ~/.cursor/mcp_config.json - Windows: %USERPROFILE%\.cursor\mcp_config.json

IBM watsonx Code Assistant (Bob)の場合:

設定ファイルの場所: - macOS: ~/Library/Application Support/Code/User/globalStorage/ibm.watsonx-code-assistant/mcp_config.json - Windows: %APPDATA%\Code\User\globalStorage\ibm.watsonx-code-assistant\mcp_config.json - Linux: ~/.config/Code/User/globalStorage/ibm.watsonx-code-assistant/mcp_config.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "mcpServers": {
    "instana": {
      "command": "npx",
      "args": ["-y", "@instana/mcp-server-instana"],
      "env": {
        "INSTANA_BASE_URL": "https://<your-tenant>.instana.io",
        "INSTANA_API_TOKEN": "<your-api-token>"
      }
    }
  }
}

APIトークンの権限設定

MCP Serverが正常に動作するために必要な最小限のAPIトークン権限は以下の通りです。

必須権限: - Configuration of applications (読み取り) - Configuration of mobile app (読み取り) - Configuration of websites (読み取り) - Access audit log (読み取り) - Access Analyze (読み取り)

Instana UIでの設定手順:

  1. Instana UIにログインします

  2. 「設定」→「セキュリティ＆アクセス」→「APIトークン」を選択します

  3. 「新規 API トークン」をクリックします

  4. トークン名を入力します（例: MCP Server Token）

  5. 上記の必須権限にチェックを入れます

  6. 「保存」をクリックしてトークンを作成します

  7. 表示されたAPIトークンをコピーして、安全な場所に保存します

  8. 注意: トークンは一度しか表示されません

権限が不足している場合、特定のクエリが失敗してしまうので、事前に適切な権限を付与したAPIトークンを作成しておきましょう。

プロキシ環境での設定

企業ネットワークでプロキシを使用している場合、追加の環境変数設定が必要になります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "mcpServers": {
    "instana": {
      "command": "npx",
      "args": ["-y", "@instana/mcp-server-instana"],
      "env": {
        "INSTANA_BASE_URL": "https://<your-tenant>.instana.io",
        "INSTANA_API_TOKEN": "<your-api-token>",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

具体的なユースケース

ユースケース1: インシデント調査の効率化

背景・課題: 本番環境でエラー率が急増し、原因を特定する必要があります。従来はInstana UIを開いて複数の画面を遷移しながら調査していましたが、かなり時間がかかっていました。

解決方法: MCP Serverを使用することで、AI開発ツール内から自然言語でInstanaのデータを照会でき、迅速に原因を特定できます。

手順:

  1. 自然言語でクエリを実行
1
2
3
「過去1時間のエラー率が高いサービスを教えて」
「payment-serviceの最新のエラートレースを表示して」
「データベース接続エラーの発生頻度を確認して」
  1. 取得した情報を基に原因を特定し、修正を実施

期待される効果: - インシデント調査時間: 15分 → 3分（80%削減） - 複数画面の遷移が不要になり、調査フローが効率化 - AIによる関連情報の自動提示により、見落としが減少

ユースケース2: パフォーマンス最適化の分析

背景・課題: アプリケーションのレスポンスタイムが悪化しており、ボトルネックを特定する必要があります。できれば開発中のコードエディタから離れずに分析したいと考えています。

解決方法: Cursor内でMCP Serverを使用することで、コーディング中にリアルタイムでパフォーマンスデータを確認できます。

手順:

  1. コード編集中にパフォーマンスデータを照会
1
2
3
「user-serviceの平均レスポンスタイムを教えて」
「最も遅いエンドポイントTOP5を表示して」
「データベースクエリの実行時間を確認して」

  1. 特定したボトルネックに対してコードを最適化

  2. デプロイ後、再度パフォーマンスを確認

1
「user-serviceのレスポンスタイムは改善した？」

期待される効果: - パフォーマンス分析時間: 20分 → 5分（75%削減） - コードエディタとInstana UIの切り替えが不要 - 最適化の効果を即座に確認可能

ユースケース3: SLO違反の早期検知と対応

背景・課題: SLO違反が発生した際、迅速に状況を把握し、関係者に報告する必要があります。

解決方法: MCP Serverを使用することで、SLOの状態を自然言語で照会でき、レポートも自動生成できます。

手順:

  1. MCP Serverの設定を確認

  2. SLOの状態を照会

1
2
3
「現在SLOに違反しているサービスを教えて」
「payment-serviceのSLO達成率を確認して」
「過去24時間のSLO違反の履歴を表示して」
  1. 詳細情報を取得
1
2
「payment-serviceのエラーバジェットの残量は？」
「どのエンドポイントがSLO違反の原因？」
  1. AIに状況レポートの作成を依頼
1
「上記の情報を基に、SLO違反の状況レポートを作成して」

期待される効果: - SLO違反の検知から報告まで: 10分 → 2分（80%削減） - 自動生成されたレポートにより、報告の品質が向上 - 迅速な対応により、サービス品質の維持が可能

実運用での注意点・ベストプラクティス

APIトークンの管理

  • APIトークンは環境変数として設定し、設定ファイルに直接記載しないようにしましょう
  • 定期的にトークンをローテーションすることをお勧めします
  • 最小権限の原則に従い、必要な権限のみを付与しましょう

パフォーマンスへの影響

  • MCP Serverは各クエリごとにInstana APIを呼び出すため、頻繁なクエリはAPI制限に達する可能性があります
  • 大量のデータを取得する場合は、時間範囲を適切に制限しましょう
  • キャッシュ機能を活用し、同じクエリの繰り返しを避けることが大切です

セキュリティ考慮事項

  • MCP Serverの設定ファイルには機密情報が含まれるため、適切なファイル権限を設定しておきましょう 
    1
2
    # macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • 共有PCでは使用を避けるか、使用後にAPIトークンを無効化しましょう
  • ログファイルに機密情報が記録されないよう注意が必要です

トラブルシューティングの効率化

  • よく使用するクエリパターンをドキュメント化しておくと便利です
  • チーム内でクエリのベストプラクティスを共有しましょう
  • 複雑なクエリは段階的に実行し、結果を確認しながら進めることをお勧めします

よくあるトラブルと解決方法

MCP Serverが起動しない

症状: AI開発ツールを起動してもMCP Serverが利用できない、またはエラーメッセージが表示されます。

原因: - 設定ファイルのJSON形式が正しくありません - npxコマンドが見つかりません（Node.jsがインストールされていません） - 環境変数の設定が正しくありません

解決方法:

  1. 設定ファイルのJSON形式を確認
1
2
3
4
5
# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json
  1. Node.jsのインストールを確認
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Node.jsのバージョン確認
node --version

# npxコマンドの確認
npx --version

# Node.jsがインストールされていない場合
# macOS (Homebrew)
brew install node

# Windows (Chocolatey)
choco install nodejs

# Linux (Ubuntu/Debian)
sudo apt install nodejs npm
  1. 環境変数の値を確認
1
2
# 手動でMCP Serverを起動してエラーを確認
npx -y @instana/mcp-server-instana

APIトークンの権限エラー

症状: 特定のクエリを実行すると「権限がありません」というエラーが返されます。

原因: APIトークンに必要な権限が付与されていません。

解決方法:

  1. Instana UIでAPIトークンの権限を確認
1
Settings → Team Settings → API Tokens → [該当トークン]
  1. 必要な権限を追加
1
2
3
4
5
6
必須権限:
- Configuration of applications (読み取り)
- Configuration of mobile app (読み取り)
- Configuration of websites (読み取り)
- Access audit log (読み取り)
- Access Analyze (読み取り)

  1. 設定ファイルのAPIトークンを更新

  2. AI開発ツールを再起動

プロキシ環境での接続エラー

症状: 企業ネットワーク内でMCP Serverが「接続できません」というエラーを返します。

原因: プロキシ設定が不足しています。

解決方法:

  1. プロキシ設定を追加
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "mcpServers": {
    "instana": {
      "command": "npx",
      "args": ["-y", "@instana/mcp-server-instana"],
      "env": {
        "INSTANA_BASE_URL": "https://example.instana.io",
        "INSTANA_API_TOKEN": "your-api-token-here",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}
  1. プロキシの認証が必要な場合
1
2
3
4
5
6
{
  "env": {
    "HTTP_PROXY": "http://username:password@proxy.company.com:8080",
    "HTTPS_PROXY": "http://username:password@proxy.company.com:8080"
  }
}

  1. AI開発ツールを再起動

  2. 接続を確認

1
「Instanaに接続できているか確認して」

レスポンスが遅い

症状: クエリの実行に時間がかかり、タイムアウトしてしまうことがあります。

原因: - 取得するデータ量が多すぎます - 時間範囲が広すぎます - Instana APIの制限に達しています

解決方法:

  1. 時間範囲を制限
1
2
悪い例: 「過去1週間のすべてのトレースを表示して」
良い例: 「過去1時間のエラートレースを表示して」
  1. 取得するデータを絞り込む
1
2
悪い例: 「すべてのサービスのメトリクスを表示して」
良い例: 「payment-serviceのレスポンスタイムを表示して」
  1. API制限を確認
1
2
3
# Instana APIの制限を確認
curl -H "Authorization: apiToken <your-api-token>" \
  https://<your-tenant>.instana.io/api/application-monitoring/settings/api-tokens
  1. 必要に応じて、複数のクエリに分割して実行