IBM Instana MCP Server

官方

IBM Instana MCP 伺服器可實現與 IBM Instana 可觀測性平台的無縫互動，讓您直接在開發工作流程中存取即時的可觀測性資料。

GitHub
22

你可以用 IBM Instana MCP 做什麼？

  • 擷取基礎設施快照 — 使用 get_infra_snapshot 查詢特定主機、程序或容器的快照。
  • 分析應用程式或服務指標 — 透過 get_app_metrics 或 get_service_metrics 請求呼叫次數、錯誤或延遲的時間序列指標。
  • 列出作用中的警示與事件 — 經由 get_alerts 和 get_incidents 取得當前警示、事件或全域智慧警示。
  • 檢視 Kubernetes 事件 — 使用 get_k8s_events 拉取叢集或命名空間的最新 Kubernetes 事件。
  • 查詢網站監控資料 — 透過 get_website_metrics 擷取網站效能指標或信標結果。

文件

目錄

IBM Instana 的 MCP 伺服器

📚 快速連結

Instana MCP 伺服器可讓您與 Instana 可觀測性平台無縫互動，讓您能夠直接在開發工作流程中存取即時的可觀測性資料。

它作為客戶端（例如 AI 代理程式或自訂工具）與 Instana REST API 之間的橋樑，將使用者查詢轉換為 Instana API 請求，並將回應格式化為結構化、易於使用的格式。

此伺服器同時支援 Streamable HTTP 和 Stdio 傳輸模式，以實現與不同 MCP 客戶端的最大相容性。如需更多詳細資訊，請參閱 MCP 傳輸模式規範。

架構概覽

graph LR
    subgraph "Application Host Process"
        MH[MCP Host]
        MSI[Instana MCP Server]
        MST[ProductA MCP Server]
        MSC[ProductB MCP Server]

        MH <--> MSI
        MH <--> MSC
        MH <--> MST
    end

    subgraph "Remote Service"
        II[Instana Instance]
        TI[ProductA Instance]
        CI[ProductB Instance]

        MSI <--> II
        MST <--> TI
        MSC <--> CI
    end

    subgraph "LLM"
        L[LLM]
        MH <--> L
    end

工作流程

考慮一個簡單的範例：您正在使用連接到 Instana MCP 伺服器的 MCP 主機（例如 Claude Desktop、VS Code 或其他客戶端）。當您請求有關 Instana 警示的資訊時，會發生以下過程：

  1. MCP 客戶端從 Instana MCP 伺服器擷取可用工具的清單
  2. 您的查詢會與工具描述一起傳送給 LLM
  3. LLM 分析可用的工具，並選擇適當的工具來擷取 Instana 警示
  4. 客戶端透過 Instana MCP 伺服器執行所選的工具
  5. 結果（最新的警示）會傳回給 LLM
  6. LLM 會制定自然語言回應
  7. 回應會顯示給您
sequenceDiagram
    participant User
    participant ChatBot as MCP Host
    participant MCPClient as MCP Client
    participant MCPServer as Instana MCP Server
    participant LLM
    participant Instana as Instana Instance

    ChatBot->>MCPClient: Load available tools from MCP Server
    MCPClient->>MCPServer: Request available tool list
    MCPServer->>MCPClient: Return list of available tools
    User->>ChatBot: Ask "Show me the latest alerts from Instana for application robot-shop"
    ChatBot->>MCPClient: Forward query
    MCPClient->>LLM: Send query and tool description
    LLM->>MCPClient: Select appropriate tool(s) for Instana alert query
    MCPClient->>MCPServer: Execute selected tool(s)
    MCPServer->>Instana: Retrieve alerts for application robot-shop
    MCPServer->>MCPClient: Send alerts of Instana result
    MCPClient->>LLM: Forward alerts of Instana
    LLM->>ChatBot: Generate natural language response for Instana alerts
    ChatBot->>User: Show Instana alert response

先決條件

選項 1：從 PyPI 安裝（建議）

使用 mcp-instana 最簡單的方式是直接從 PyPI 安裝：

pip install mcp-instana

安裝後，您可以直接使用 mcp-instana 命令來執行伺服器。

選項 2：開發環境安裝

對於開發或本機自訂，您可以複製並在本機設定專案。

安裝 uv

此專案使用 uv，一個快速的 Python 套件安裝器和解析器。若要安裝 uv，您有幾個選項：

使用 pip：

pip install uv

使用 Homebrew (macOS)：

brew install uv

如需更多安裝選項和詳細說明，請造訪 uv 文件。

設定環境

安裝 uv 後，請透過執行以下命令來設定專案環境：

uv sync

Streamable HTTP 模式的標頭驗證

使用 Streamable HTTP 模式時，您必須透過 HTTP 標頭傳遞 Instana 憑證。這種方法透過以下方式增強了安全性和靈活性：

  • 避免將憑證儲存在環境變數中
  • 能夠對不同的請求使用不同的憑證
  • 支援無法修改環境變數的共享環境
  • 同時支援 API 權杖和基於工作階段的驗證

支援的驗證模式：

1. API 權杖驗證（直接 API 呼叫）

必要的標頭：

  • instana-base-url：您的 Instana 執行個體 URL
  • instana-api-token：您的 Instana API 權杖

範例：

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-api-token: your-api-token"

2. 工作階段權杖驗證（UI 發起的呼叫）

必要的標頭：

  • instana-base-url：您的 Instana 執行個體 URL
  • instana-auth-token：來自 UI 後端的工作階段驗證權杖
  • instana-csrf-token：來自 UI 後端的 CSRF 權杖
  • instana-cookie-name：（選用）用於工作階段驗證的 Cookie 名稱（預設：instanaAuthToken）

範例：

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-auth-token: your-session-token"
--header "instana-csrf-token: your-csrf-token"
--header "instana-cookie-name: in-token"

3. JWT 權杖驗證（IBM 平台整合）

必要的標頭：

  • instana-base-url：您的 Instana 執行個體 URL
  • instana-jwt-token：來自 IBM 平台的 JWT 權杖
  • instana-csrf-token：用於請求驗證的 CSRF 權杖

設定範例：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp",
        "--allow-http",
        "--header",
        "instana-base-url: https://your-instana-instance.instana.io",
        "--header",
        "instana-jwt-token: your_jwt_token_here",
        "--header",
        "instana-csrf-token: your_csrf_token_here"
      ]
    }
  }
}

驗證優先順序：

  1. JWT 權杖（如果與 CSRF 權杖一起提供）- 對於 IBM 平台整合具有優先權
  2. 工作階段權杖（如果同時提供了 auth_token 和 csrf_token）
  3. API 權杖（如果提供）- 標準驗證
  4. 環境變數 (INSTANA_API_TOKEN) - 備用方案

驗證流程：

  1. 每個請求中都必須存在 HTTP 標頭
  2. 伺服器根據優先順序驗證憑證
  3. 沒有有效驗證的請求將會失敗

此設計確保了安全的憑證傳輸，並支援多種驗證流程，包括透過 WebSocket → 協調器 → MCP 伺服器發起的 UI 呼叫。

請確保使用的權杖具有叫用 MCP 工具的必要權限。請查看此處以獲取更多資訊。

啟動本機 MCP 伺服器

在設定任何 MCP 客戶端（Claude Desktop、GitHub Copilot 或自訂 MCP 客戶端）之前，您需要啟動本機 MCP 伺服器。伺服器支援兩種傳輸模式：Streamable HTTP 和 Stdio。

伺服器命令選項

使用 CLI（PyPI 安裝）

如果您是從 PyPI 安裝 mcp-instana，請使用 mcp-instana 命令：

mcp-instana [OPTIONS]

使用開發環境安裝

對於本機開發，請使用 uv run 命令：

uv run src/core/server.py [OPTIONS]

可用選項：

  • --transport <mode>：傳輸模式（選項：streamable-http、stdio）
  • --env KEY=VALUE：設定環境變數（可重複用於多個變數，例如 --env INSTANA_BASE_URL=https://... --env INSTANA_API_TOKEN=...）
  • --debug：啟用偵錯模式並提供額外的日誌記錄
  • --log-level <level>：設定日誌記錄層級（選項：DEBUG、INFO、WARNING、ERROR、CRITICAL）
  • --tools <categories>：要啟用的工具類別，以逗號分隔的清單（例如 infra,app,events,website）。啟用某個類別也會啟用其相關的提示。例如：--tools infra 會啟用 infra 工具和所有與 infra 相關的提示。
  • --list-tools：列出所有可用的工具類別並退出
  • --port <port>：MCP 伺服器連接埠（預設：8080，可透過 PORT 環境變數覆寫）
  • --help：顯示說明訊息並退出

以 Streamable HTTP 模式啟動

Streamable HTTP 模式提供 REST API 介面，建議用於大多數使用案例。

使用 CLI（PyPI 安裝）

# Start with all tools enabled (default)
mcp-instana --transport streamable-http

# Start with debug logging
mcp-instana --transport streamable-http --debug

# Start with a specific log level
mcp-instana --transport streamable-http --log-level WARNING

# Start with specific tool categories only
mcp-instana --transport streamable-http --tools infra,events

# Combine options (specific log level, custom tools)
mcp-instana --transport streamable-http --log-level DEBUG --tools app,events

使用開發環境安裝

# Start with all tools enabled (default)
uv run src/core/server.py --transport streamable-http

# Start with debug logging
uv run src/core/server.py --transport streamable-http --debug

# Start with a specific log level
uv run src/core/server.py --transport streamable-http --log-level WARNING

# Start with specific tool and prompts categories only
uv run src/core/server.py --transport streamable-http --tools infra,events

# Start with custom port
uv run src/core/server.py --transport streamable-http --port 9000

# Combine options (specific log level, custom tools and prompts)
uv run src/core/server.py --transport streamable-http --log-level DEBUG --tools app,events

Streamable HTTP 模式的主要功能：

  • 使用 HTTP 標頭進行驗證（無需環境變數）
  • 支援每個請求使用不同的憑證
  • 更適合共享環境
  • MCP 伺服器預設連接埠：8080
  • MCP 端點：http://0.0.0.0:8080/mcp/

以 Stdio 模式啟動

Stdio 模式使用標準輸入/輸出進行通訊，並且需要環境變數進行驗證。

使用 CLI（PyPI 安裝）

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
mcp-instana

# Or explicitly specify stdio mode
mcp-instana --transport stdio

# Option 2: Use --env flag to set environment variables directly
mcp-instana --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
mcp-instana --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

使用開發環境安裝

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
uv run src/core/server.py

# Or explicitly specify stdio mode
uv run src/core/server.py --transport stdio

# Option 2: Use --env flag to set environment variables directly
uv run src/core/server.py --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
uv run src/core/server.py --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Stdio 模式的主要功能：

  • 使用環境變數進行驗證（可透過 export 或 --env 旗標設定）
  • 透過 stdin/stdout 直接通訊
  • 某些 MCP 客戶端設定需要此模式
  • --env 旗標提供了一種無需修改 shell 環境即可設定憑證的便捷方式

工具類別

您可以僅啟用所需的工具和提示類別來最佳化伺服器效能：

使用 CLI（PyPI 安裝）

# List all available categories
mcp-instana --list-tools

# Enable specific categories
mcp-instana --transport streamable-http --tools infra,app
mcp-instana --transport streamable-http --tools events

使用開發環境安裝

# List all available categories
uv run src/core/server.py --list-tools

# Enable specific categories
uv run src/core/server.py --transport streamable-http --tools infra,app
uv run src/core/server.py --transport streamable-http --tools events

可用類別：

  • infra：基礎架構監控工具和提示（資源、目錄、拓撲、分析、指標）
  • app：應用程式效能工具和提示（資源、指標、警示、目錄、拓撲、分析、設定、全域警示）
  • events：事件監控工具和提示（Kubernetes 事件、代理程式監控）
  • website：網站監控工具和提示（指標、目錄、分析、設定）

驗證伺服器狀態

啟動後，您可以驗證伺服器是否正在執行：

對於 Streamable HTTP 模式：

# Check MCP server
curl http://0.0.0.0:8080/mcp/

# Or with custom port
curl http://0.0.0.0:9000/mcp/

對於 Stdio 模式： 伺服器將啟動並等待來自 MCP 客戶端的 stdin 輸入。

常見啟動問題

憑證問題： 如果您遇到 SSL 憑證錯誤，請確保您的 Python 環境可以存取系統憑證：

# macOS - Install certificates for Python
/Applications/Python\ 3.13/Install\ Certificates.command

連接埠已被使用： 如果連接埠 8080 已被使用，請指定不同的連接埠：

uv run src/core/server.py --transport streamable-http --port 9000

缺少相依性： 確保所有相依性都已安裝：

uv sync

設定與使用

Bob IDE

Bob 是 IBM 的 AI 驅動 IDE，原生支援 MCP 整合。Bob 提供無縫的開發體驗，內建 AI 輔助和可觀測性工具。

Streamable HTTP 模式

Streamable HTTP 模式提供了一個 REST API 介面，用於透過 HTTP 使用 JSON-RPC 進行 MCP 通訊。

步驟 1：在 Streamable HTTP 模式下啟動 MCP 伺服器

在設定 Bob 之前，您需要先在 Streamable HTTP 模式下啟動 MCP 伺服器。請參閱啟動本機 MCP 伺服器章節以取得詳細說明。

步驟 2：設定 Bob

在 Bob 面板的右上角，您會看到一個包含 MCP 伺服器的下拉選單：

選取此選項後，您應該能夠看到在專案層級或全域層級設定 MCP 的選項。

MCP 設定範圍

Bob 支援兩個層級的 MCP 設定，讓您可以選擇最適合您使用案例的範圍：

1. 全域設定（使用者層級）

全域設定會將 MCP 伺服器套用至目前使用者的所有專案。當您希望相同的 MCP 伺服器在您處理的每個專案中都可用時，這是最理想的選擇。

檔案位置：

  • macOS：~/Library/Application Support/Bob/bob_config.json
  • Windows：%APPDATA%\Bob\bob_config.json
  • Linux：~/.config/Bob/bob_config.json

2. 專案設定（專案層級）

專案設定僅將 MCP 伺服器套用至特定專案。當不同專案需要不同的 MCP 伺服器設定，或者您希望透過版本控制與團隊共享 MCP 設定時，這非常有用。

檔案位置：

  • 專案根目錄中的 .bob/bob_config.json

在全域設定與專案設定之間選擇：

  • 對於您希望在所有專案中都可用的 MCP 伺服器，請使用全域設定
  • 對於特定專案的 MCP 伺服器或要與團隊共享設定，請使用專案設定
  • 兩種設定可以共存——對於相同的伺服器名稱，專案層級設定優先於全域設定

有關 Bob 和 MCP 設定的更多資訊，請造訪：https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

本機設定：

設定 Bob 以連線到您的本機 IBM Instana MCP Server：

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

遠端設定：

設定 Bob 以連線到遠端 IBM Instana MCP Server（例如，部署在 IBM Code Engine 上）：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://app-instana-750.1zetetanw8ul.us-east.codeengine.appdomain.cloud/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

注意： 若要使用 npx，我們建議先安裝 NVM（Node 版本管理器），然後使用它來安裝 Node.js。 安裝說明可在以下位置取得：https://nodejs.org/en/download

步驟 3：測試連線

設定好 MCP 設定後，新設定的 MCP 伺服器應顯示為已啟用。綠點表示伺服器正在成功執行。

您現在可以在 Bob IDE 中執行查詢：

get me all applications from Instana in the last 24 hours

Stdio 模式

使用 CLI 進行設定（PyPI 安裝 - 建議）：

選項 1：在設定中使用環境變數：

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

選項 2：使用 --env 旗標（替代方法）：

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

注意： 如果您遇到「找不到命令」的錯誤，請使用 mcp-instana 的完整路徑。使用 which mcp-instana 尋找它，並改用該路徑。

使用開發安裝進行設定：

選項 1：在設定中使用環境變數：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

選項 2：使用 --env 旗標（替代方法）：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Claude Desktop

Claude Desktop 支援 Streamable HTTP 和 Stdio 兩種模式進行 MCP 整合。

透過編輯設定檔來設定 Claude Desktop：

檔案位置：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json

Streamable HTTP 模式

Streamable HTTP 模式提供了一個 REST API 介面，用於透過 HTTP 使用 JSON-RPC 進行 MCP 通訊。

步驟 1：在 Streamable HTTP 模式下啟動 MCP 伺服器

在設定 Claude Desktop 之前，您需要先在 Streamable HTTP 模式下啟動 MCP 伺服器。請參閱啟動本機 MCP 伺服器章節以取得詳細說明。

步驟 2：設定 Claude Desktop

設定 Claude Desktop 以透過標頭傳遞 Instana 憑證：

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

注意： 若要使用 npx，我們建議先安裝 NVM（Node 版本管理器），然後使用它來安裝 Node.js。 安裝說明可在以下位置取得：https://nodejs.org/en/download

步驟 3：測試連線

重新啟動 Claude Desktop。您現在應該會在 Claude Desktop 介面中看到 IBM Instana MCP Server，如下所示：

您現在可以在 Claude Desktop 中執行查詢：

get me all endpoints from Instana

Stdio 模式

使用 CLI 進行設定（PyPI 安裝 - 建議）：

選項 1：在設定中使用環境變數：

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

選項 2：使用 --env 旗標（替代方法）：

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

注意： 如果您遇到「找不到命令」的錯誤，請使用 mcp-instana 的完整路徑。使用 which mcp-instana 尋找它，並改用該路徑。

使用開發安裝進行設定：

選項 1：在設定中使用環境變數：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

選項 2：使用 --env 旗標（替代方法）：

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Kiro 設定

Kiro 是一個代理 IDE，而不是可以下載到 VS Code 或其他 IDE 中的擴充功能。

步驟 1：從 https://kiro.dev/. 下載並安裝適用於您作業系統的 Kiro**

步驟 2：安裝完成後，啟動 Kiro 並在 IDE 中開啟任何專案。 alt text

步驟 3：點擊左側邊欄中的 Kiro（Ghost）圖示以存取 Kiro 的功能。 alt text

步驟 4：在 MCP 伺服器區塊的右上角選取「編輯設定」圖示。 alt text

步驟 5：開啟 MCP 伺服器設定檔（mcp.json），並根據您偏好的傳輸模式進行設定：

Streamable HTTP 模式（建議用於 Kiro）

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

注意： 在使用此設定之前，請確保以 streamable-http 模式啟動 MCP 伺服器：

mcp-instana --transport streamable-http

Stdio 模式

選項 1：在設定中使用環境變數：

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

選項 2：使用 --env 旗標（替代方法）：

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

步驟 6：儲存檔案後，點擊「啟用 MCP」按鈕，您將在 Kiro 的左下角區塊看到您的 MCP 伺服器及其可用工具。 alt text

步驟 7：前往 AI 聊天面板，輸入與您的 MCP 伺服器相關的提示，並直接在 Kiro 中檢視回應。 alt text

GitHub Copilot

GitHub Copilot 透過 VS Code 設定支援 MCP 整合。 有關 GitHub Copilot 與 VS Code 的整合，請參閱此設定指南。

Streamable HTTP 模式

步驟 1：在 Streamable HTTP 模式下啟動 MCP 伺服器

在設定 VS Code 之前，您需要先在 Streamable HTTP 模式下啟動 MCP 伺服器。請參閱啟動本機 MCP 伺服器章節以取得詳細說明。

步驟 2：設定 VS Code

請參閱在 VS Code 中使用 MCP 伺服器以取得詳細設定。

您可以直接使用以下設定來建立或更新 .vscode/mcp.json：

{
  "servers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ],
      "env": {
        "PATH": "/usr/local/bin:/bin:/usr/bin",
        "SHELL": "/bin/sh"
      }
    }
  }
}

注意： 將以下值替換為您的實際設定：

  • instana-base-url：您的 Instana 執行個體 URL
  • instana-api-token：您的 Instana API 權杖
  • command：更新 npx 路徑以符合您系統的 Node.js 安裝（例如，/path/to/your/node/bin/npx）
  • 環境變數：根據您的系統需要調整 PATH 和其他環境變數

Stdio 模式

步驟 1：建立 VS Code MCP 設定

使用 CLI（PyPI 安裝 - 建議）：

在您的專案根目錄中建立 .vscode/mcp.json：

選項 1：在設定中使用環境變數：

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

選項 2：使用 --env 旗標（替代方法）：

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

使用開發安裝：

在您的專案根目錄中建立 .vscode/mcp.json：

選項 1：在設定中使用環境變數：

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

選項 2：使用 --env 旗標（替代方法）：

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

注意： 將以下值替換為您的實際設定：

  • 對於 CLI 安裝：確保 mcp-instana 在您的 PATH 中
  • 對於開發安裝：
    • command：更新 uv 路徑以符合您系統的 uv 安裝（例如，/path/to/your/uv/bin/uv 或 /usr/local/bin/uv）
    • --directory：使用您的 mcp-instana 專案目錄的絕對路徑進行更新
  • INSTANA_BASE_URL：您的 Instana 執行個體 URL
  • INSTANA_API_TOKEN：您的 Instana API 權杖

步驟 2：在 VS Code 中管理伺服器

  1. 開啟 .vscode/mcp.json - 您將在頂部看到伺服器管理控制項
  2. 點擊 Start 旁邊的 Instana MCP Server 以啟動伺服器
  3. 執行狀態以及工具數量表示伺服器正在執行

步驟 3：測試整合

在 GitHub Copilot 中切換到代理模式並重新載入工具。 以下是 GitHub Copilot 回應的範例：

GitHub Copilot Response

Mistral AI

Mistral AI 僅透過 Streamable HTTP 模式支援 MCP 整合。

步驟 1：在 Streamable HTTP 模式下啟動 MCP 伺服器

透過提供您的 Instana 憑證，在 Streamable HTTP 模式下啟動 MCP 伺服器。執行以下命令：

uv run src/core/server.py --transport streamable-http \
  --api-token "your_instana_api_token" \
  --base-url "https://your-instana-instance.instana.io" \
  --port 8080

步驟 2：使用 Ngrok 設定連接埠轉發

設定連接埠轉發以公開您的本機伺服器。請遵循 Ngrok 設定文件以取得詳細說明。

步驟 3：設定 Mistral AI

  1. 導覽至左側邊欄中的 Intelligence 標籤，然後選取 Connectors Mistral HomePage

  2. 點擊 Add Connector Connector

  3. 透過輸入連接器名稱和 Ngrok 轉發的 MCP 伺服器 URL 來建立自訂連接器 Custom Connector

  4. 開始新的聊天工作階段，並確認 MCP 工具已啟用。您可以在這裡檢視回應 Testing MCP connection Response

支援的功能

  • 統一應用程式與基礎架構管理 (manage_instana_resources)
    • 應用程式指標
      • 使用彈性篩選查詢應用程式指標
      • 列出服務與端點
      • 按標籤分組並彙總指標
    • 應用程式警示設定
      • 尋找作用中的警示設定
      • 取得警示設定版本
      • 建立、更新與刪除警示設定
      • 啟用、停用與還原警示設定
      • 更新歷史基準
    • 全域應用程式警示設定
      • 管理全域警示設定
      • 全域警示的版本控制
    • 應用程式設定
      • 管理應用程式視角
      • 設定端點與服務
      • 管理手動服務
    • 應用程式目錄
      • 取得應用程式標籤目錄
      • 取得應用程式指標目錄
  • 基礎架構分析 (analyze_infrastructure)
    • 針對實體/指標查詢的兩階段引導
    • 動態支援來自 Instana API 目錄的所有實體類型（JVM、Kubernetes、Docker、主機、資料庫、訊息佇列等）
    • 自動與您的 Instana 安裝中可用的外掛程式同步
    • 彈性的指標彙總（最大值、平均值、總和等）
    • 依標籤和屬性進行進階篩選
    • 分組與排序功能
    • 時間範圍查詢
  • 統一事件管理 (manage_events)
    • 事件監控
      • 依 ID 取得事件 (operation="get_event")
      • 依多個 ID 取得事件 (operation="get_events_by_ids")
      • 取得代理程式監控事件 (operation="get_agent_monitoring_events")
      • 取得 Kubernetes 資訊事件 (operation="get_kubernetes_info_events")
      • 取得事件 (operation="get_events")
    • 智慧路由至專門的事件工具
    • 統一的參數驗證（時間範圍、max_events）
    • 支援自然語言時間範圍（「過去 24 小時」、「過去 2 天」）
    • 事件篩選與最佳化
  • 統一網站管理 (manage_website_resources)
    • 網站分析 (resource_type="analyze")
      • 取得網站信標群組 - 分組/彙總的信標資料 (operation="get_beacon_groups")
      • 取得網站信標 - 具備分頁功能的個別信標資料 (operation="get_beacons")
      • 自動標籤驗證與基於目錄的引導工作流程
      • 回應摘要（減少 70-80% 的酬載）
      • 支援多種信標類型：PAGELOAD、PAGECHANGE、RESOURCELOAD、CUSTOM、HTTPREQUEST、ERROR
    • 網站目錄 (resource_type="catalog")
      • 取得網站指標目錄 (operation="get_metrics")
      • 依信標類型與使用案例取得網站標籤目錄 (operation="get_tag_catalog")
    • 網站設定 (resource_type="configuration")
      • 取得所有網站 (operation="get_all")
      • 依 ID 或名稱取得網站，具備自動名稱解析功能 (operation="get")
    • 進階設定 - 唯讀 (resource_type="advanced_config")
      • 取得地理位置設定 (operation="get_geo_config")
      • 取得 IP 遮罩設定 (operation="get_ip_masking")
      • 取得地理對應規則 (operation="get_geo_rules")
  • 統一自動化管理 (manage_automation)
    • 動作目錄 (resource_type="catalog")
      • 列出所有可用的自動化動作 (operation="get_actions")
      • 取得特定動作的詳細資訊 (operation="get_action_details")
      • 依名稱/描述搜尋相符的動作 (operation="get_action_matches")
      • 依應用程式或快照 ID 與時間範圍取得相符的動作 (operation="get_action_matches_by_id_and_time_window")
      • 取得可用的動作類型 (operation="get_action_types")
      • 取得可用的動作標籤 (operation="get_action_tags")
    • 動作歷史記錄 (resource_type="history")
      • 列出動作執行實例並進行篩選 (operation="list")
      • 取得特定動作執行的詳細資訊 (operation="get_details")
  • 自訂儀表板 (manage_custom_dashboards)
    • 取得所有自訂儀表板
    • 依 ID 取得特定儀表板
    • 建立新的自訂儀表板
    • 更新現有的自訂儀表板
    • 刪除自訂儀表板
    • 取得儀表板的可共用使用者
    • 取得儀表板的可共用 API 權杖

可用工具

工具類別說明
manage_applications應用程式與基礎架構用於管理應用程式指標、警示設定、設定與目錄的統一工具
manage_websites網站監控用於網站分析、目錄、設定與進階設定操作的統一智慧路由器
manage_custom_dashboards自訂儀表板用於管理自訂儀表板 CRUD 操作的統一工具
analyze_infrastructure基礎架構分析具備實體/指標引導功能的兩階段基礎架構分析
manage_automation自動化用於自動化的統一智慧路由器：瀏覽動作目錄與檢視執行歷史記錄
manage_events事件用於事件監控的統一智慧路由器：依 ID 取得事件、依多個 ID 取得事件、Kubernetes 事件、代理程式監控事件與所有事件
manage_sloSLO 管理用於 SLO 設定、報告、警示與修正時段的統一智慧路由器，具備智慧時區處理功能
manage_releases版本管理用於版本追蹤的統一智慧路由器：以分頁與名稱篩選列出版本、取得版本詳細資訊、建立/更新/刪除版本，並支援時區
manage_maintenance_windows維護時段用於維護時段生命週期管理的統一智慧路由器：建立、修改、關閉與列出維護時段，支援範本與 ServiceNow 整合
manage_mobile_apps行動應用程式監控用於行動應用程式監控的統一智慧路由器：分析信標、效能指標、設定與警示管理

👉 如需詳細的工具文件、功能與技術參考，請參閱工具與範例

工具篩選

MCP 伺服器支援選擇性工具載入，以最佳化效能並減少資源使用。您可以僅針對特定使用案例啟用所需的工具類別。

可用的工具類別

  • router：統一應用程式與基礎架構管理

    • manage_instana_resources：用於應用程式指標、警示設定、設定與目錄的單一工具
    • 支援應用程式視角、端點、服務與手動服務
    • 管理應用程式特定與全域警示設定
    • 提供應用程式標籤目錄與指標目錄的存取

  • dashboard：自訂儀表板管理

    • manage_custom_dashboards：自訂儀表板的 CRUD 操作
    • 支援儀表板的建立、擷取、更新與刪除
    • 管理儀表板的可共用使用者與 API 權杖

  • infra：基礎架構分析工具

    • analyze_infrastructure：具備實體/指標引導功能的兩階段基礎架構分析
    • 動態支援 Instana 安裝中所有可用的實體類型（自動從 API 目錄載入）
    • 包含 JVM、Kubernetes、Docker、主機、資料庫、訊息佇列，以及任何自訂或新增的實體類型
    • 彈性的指標彙總、篩選、分組與時間範圍查詢

  • automation：自動化動作工具

    • manage_automation：用於自動化目錄與執行歷史記錄的統一智慧路由器
    • 動作目錄：瀏覽動作、取得詳細資訊、依名稱/描述搜尋、依應用程式或快照 ID 篩選
    • 動作歷史記錄：列出執行實例並進行篩選、取得執行詳細資訊

  • events：事件監控工具

    • 事件：Kubernetes 事件、代理程式監控與系統事件追蹤

  • website：網站監控工具

    • 網站指標：網站的效能測量
    • 網站目錄：網站中繼資料與定義
    • 網站分析：網站效能分析
    • 網站設定：網站設定管理

  • slo：服務水準目標 (SLO) 管理

    • manage_slo：用於全方位 SLO 操作的統一智慧路由器
    • 設定管理：建立、讀取、更新、刪除 SLO 設定，支援基於時間與基於事件的指標
    • 報告產生：產生詳細的 SLO 報告，包含 SLI 值、錯誤預算、消耗率與時間序列圖表
    • 警示設定：管理用於錯誤預算監控與消耗率追蹤的 SLO 警示設定
    • 修正時段：建立與管理維護時段，以將計畫性停機時間排除在 SLO 計算之外
    • 智慧時區處理：針對日期時間輸入的自動時區引導，以確保準確的時間上下文
    • 兩階段引導：針對需要多個輸入的複雜操作，進行互動式參數收集

  • releases：版本追蹤與部署管理

    • manage_releases：用於版本操作的統一智慧路由器
    • 列出版本：以高效分頁（page_number、page_size）與基於名稱的篩選取得所有版本
    • 版本詳細資訊：依 ID 擷取特定版本資訊，包含應用程式、服務與範圍
    • 建立/更新/刪除：用於版本管理的完整 CRUD 操作
    • 智慧時區處理：針對版本開始時間的自動時區引導
    • 高效分頁：透過適當的頁面導覽避免重複的資料擷取
    • 名稱篩選：不區分大小寫的子字串比對，以依名稱尋找版本

  • maintenance_window：維護時段生命週期管理

    • manage_maintenance_windows：用於維護時段操作的統一智慧路由器
    • 時段操作：建立、修改、關閉與列出維護時段（作用中、已排程、全部、已過期）
    • 批次操作：同時為多個應用程式建立維護時段
    • 範本支援：針對常見情境的預定義範本（部署、資料庫遷移、基礎架構升級、緊急情況、例行性）
    • 週期性時段：使用 RFC 5545 RRULE 格式支援週期性維護時段
    • ServiceNow 整合：可選的 ServiceNow 變更請求整合
    • 驗證：建立時段前的參數驗證
    • 彈性持續時間：以分鐘、小時或天為單位指定持續時間

  • mobile_app：行動應用程式監控

    • manage_mobile_apps：用於行動應用程式監控操作的統一智慧路由器
    • 信標分析：透過分組和篩選查詢行動應用程式信標資料
    • 效能指標：追蹤工作階段持續時間、當機率和 HTTP 請求效能
    • 地理分析：按國家、城市和區域分析使用者分佈
    • 裝置分析：監控不同裝置、平台和作業系統版本的效能
    • 組態管理：管理行動應用程式組態、地理位置和 IP 遮罩設定
    • 警示管理：設定和管理行動應用程式警示組態

使用範例

使用 CLI（PyPI 安裝）

# Enable only router (unified app/infra management) and events tools
mcp-instana --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
mcp-instana --tools infra --transport streamable-http

# Enable router and infrastructure analysis
mcp-instana --tools router,infra --transport streamable-http

# Enable events and website tools
mcp-instana --tools events,website --transport streamable-http

# Enable dashboard and router tools
mcp-instana --tools dashboard,router --transport streamable-http

# Enable releases and events tools
mcp-instana --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
mcp-instana --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
mcp-instana --transport streamable-http

# List all available tool categories and their tools
mcp-instana --list-tools

使用開發環境安裝

# Enable only router (unified app/infra management) and events tools
uv run src/core/server.py --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
uv run src/core/server.py --tools infra --transport streamable-http

# Enable router and infrastructure analysis
uv run src/core/server.py --tools router,infra --transport streamable-http

# Enable events and website tools
uv run src/core/server.py --tools events,website --transport streamable-http

# Enable dashboard and router tools
uv run src/core/server.py --tools dashboard,router --transport streamable-http

# Enable releases and events tools
uv run src/core/server.py --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
uv run src/core/server.py --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
uv run src/core/server.py --transport streamable-http

# List all available tool categories and their tools
uv run src/core/server.py --list-tools

工具篩選的優點

  • 效能：減少啟動時間和記憶體使用量
  • 安全性：限制僅暴露必要的 API
  • 清晰度：專注於特定使用案例（例如，僅基礎架構監控）
  • 資源效率：降低 CPU 和網路使用量

👉 有關使用範例和提示，請參閱範例提示

Docker 部署

MCP Instana 伺服器可以在生產環境中使用 Docker 部署。Docker 設定已針對安全性、效能和最小資源使用量進行最佳化。

Docker 架構

本專案採用雙檔案依賴管理策略：

pyproject.toml

  • 用途：開發和生產環境的統一組態
  • 依賴項：所有必要的依賴項，以及可選的開發依賴項
  • 使用方式：本機開發、測試、CI/CD 和 Docker 生產環境建置
  • 優點：所有依賴項的單一事實來源，簡化維護

建置 Docker 映像檔

先決條件

  • 已安裝並執行 Docker
  • 可存取專案原始碼
  • 用於多架構建置的 Docker BuildKit（在較新的 Docker 版本中預設啟用）

建置指令

# Build the optimized production image
docker build -t mcp-instana:latest .

# Build with a specific tag
docker build -t mcp-instana:<image_tag> .

#### **Run Command**
# Run the container (no credentials needed in the container)
docker run -p 8080:8080 mcp-instana

# Run with custom port
docker run -p 8081:8080 mcp-instana

📖 有關全面的 Docker 文件，包括多架構建置、Docker Compose 設定、安全性最佳實務和生產環境部署範例，請參閱 DOCKER.md。

疑難排解

Docker 問題

容器無法啟動

# Check container logs
docker logs <container_id>
# Common issues:
# 1. Port already in use
# 2. Invalid container image
# 3. Missing dependencies
# Credentials are passed via HTTP headers from the MCP client

連線問題

# Test container connectivity
docker exec -it <container_id> curl http://127.0.0.1:8080/health
# Check port mapping
docker port <container_id>

效能問題

# Check container resource usage
docker stats <container_id>
# Monitor container health
docker inspect <container_id> | grep -A 10 Health

一般問題

  • GitHub Copilot

    • 如果您遇到 GitHub Copilot 的問題，請嘗試在 mcp.json 檔案中啟動/停止/重新啟動伺服器，並一次僅保持一個伺服器執行。

  • 憑證問題

    • 如果您遇到憑證問題，例如 [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate：
      • 檢查您是否可以使用 curl 或 wget 並啟用 SSL 驗證來連線到 Instana API 端點。
        • 如果可行，您的 Python 環境可能無法驗證憑證，並且可能無法存取與您的 shell 或系統相同的憑證。請確保您的 Python 環境使用系統憑證 (macOS)。您可以透過將憑證安裝到 Python 來執行此操作： //Applications/Python\ 3.13/Install\ Certificates.command
      • 如果您無法在啟用 SSL 驗證的情況下連線到端點，請嘗試在不使用 SSL 驗證的情況下連線。如果可行，請檢查您系統的 CA 憑證，並確保它們是最新的。