IBM Instana MCP Server

官方

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

你可以用 IBM Instana MCP 做什麼？

查詢 Instana 警示 — 要求取得 Instana 針對特定應用程式的最新警示，並獲得自然語言摘要。
管理應用程式與基礎架構 — 透過伺服器的工具擷取應用程式指標、警示設定、設定值與基礎架構快照。
追蹤 SLO 與版本發佈 — 列出 SLO 設定與報告，或瀏覽及管理版本發佈記錄，並支援時區處理。
處理維護時段 — 建立、修改、關閉及列出維護時段，包括範本與 ServiceNow 整合支援。
監控網站與行動應用程式 — 分析網站與行動應用程式的效能指標、beacon 與工作階段重播資料。
篩選已啟用的工具類別 — 使用 --tools 選項，僅以您需要的工具類別啟動伺服器。

文件

🔒 預設啟用 SSL：從此版本 1.0.3 開始，所有對外發出的 Instana API 呼叫皆預設啟用 SSL 憑證驗證。您可以透過 CLI 旗標、環境變數或 config.yaml 自訂此行為（停用、提供自訂 CA 憑證包等）。完整詳情請參閱 SSL 憑證驗證。

IBM Instana MCP Server

快速連結

工具與範例 - 包含真實世界範例的完整工具文件
隱私權政策 - 資料處理與隱私權資訊
Docker 部署指南 - 完整的 Docker 部署、多架構建置與生產環境設定

Instana MCP server 可與 Instana 可觀測性平台順暢互動，讓您直接在開發工作流程中存取即時的可觀測性資料。

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

此 server 同時支援 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 Server 的 MCP Host（例如 Claude Desktop、VS Code 或其他用戶端）。當您請求 Instana 警示的相關資訊時，會發生以下流程：

MCP 用戶端從 Instana MCP server 擷取可用工具的清單
您的查詢會連同工具描述一併傳送給 LLM
LLM 分析可用的工具，並選擇適合的工具來擷取 Instana 警示
用戶端透過 Instana MCP server 執行所選工具
結果（最新警示）會回傳給 LLM
LLM 擬定自然語言回應
回應會顯示給您

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

先決條件

python - 版本 3.10 或更高
pip - 版本 21.3 或更高（僅以 pypi 為基礎的安裝需要）
uv - 版本 0.11.6 或更高（僅開發安裝需要）

安裝 Instana MCP server

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

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

pip install mcp-instana

安裝後，您可以直接使用 mcp-instana 指令執行 server。

選項 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 token 與以 session 為基礎的驗證

支援的驗證模式：

1. API Token 驗證（直接 API 呼叫）

必要標頭：

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

範例：

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

2. Session Token 驗證（由 UI 發起的呼叫）

必要標頭：

instana-base-url：您的 Instana 執行個體 URL
instana-auth-token：來自 UI 後端的 session 驗證 token
instana-csrf-token：來自 UI 後端的 CSRF token
instana-cookie-name：（選用）用於 session 驗證的 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 Token 驗證（IBM 平台整合）

必要標頭：

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

範例設定：

{
  "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"
      ]
    }
  }
}

驗證優先順序：

JWT Token（若連同 CSRF token 提供）- 在 IBM 平台整合中優先採用
Session Token（若同時提供 auth_token 與 csrf_token）
API Token（若有提供）- 標準驗證
環境變數（INSTANA_API_TOKEN）- 備援

驗證流程：

每個請求都必須包含 HTTP 標頭
Server 依優先順序驗證認證資訊
未通過有效驗證的請求將會失敗

此設計可確保認證資訊的安全傳輸，並支援多種驗證流程，包括透過 WebSocket → Coordinator → MCP Server 由 UI 發起的呼叫。

請確保所使用的 token 具備叫用 MCP 工具所需的權限。如需更多資訊，請參閱此處。

啟動本機 MCP Server

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

Server 指令選項

使用 CLI（PyPI 安裝）

若您是從 PyPI 安裝 mcp-instana，請使用 mcp-instana 指令：

mcp-instana [OPTIONS]

使用開發安裝

若為本機開發，請使用 uv run 指令：

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

可用選項：

--transport <mode>：傳輸模式（選項：streamable-http、stdio）
--debug：啟用偵錯模式並輸出額外記錄
--log-level <level>：設定記錄層級（選項：DEBUG、INFO、WARNING、ERROR、CRITICAL）
--tools <categories>：以逗號分隔的工具類別清單，用以啟用（例如 infra,app,events,website）。啟用某個類別也會一併啟用其相關的提示。例如：--tools infra 會啟用 infra 工具及所有 infra 相關的提示。
--list-tools：列出所有可用的工具類別後結束
--port <port>：MCP server 連接埠（預設：8080，可透過 PORT 環境變數覆寫）
--admin-port <port>：用於健康檢查的 Admin server 連接埠（預設：8601，可透過 ADMIN_PORT 環境變數覆寫）
--verify-ssl [BOOL]：啟用或停用對外發出 Instana API 呼叫的 SSL 憑證驗證（預設：true）。傳入 false/0/no 以停用。等同於設定 INSTANA_SSL_VERIFY=false。
--stream-read-buffer-size <SIZE>：串流解析器每次 I/O 讀取呼叫所使用的位元組數（預設：65536 / 64k）。可接受純位元組數或易讀的後綴：64k、64kb、64m、64mb、64g、64gb。也可透過 STREAM_READ_BUFFER_SIZE 環境變數設定。
--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 server 預設連接埠：8080
MCP 端點：http://0.0.0.0:8080/mcp/

以 Stdio 模式啟動

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

使用 CLI（PyPI 安裝）

# 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

使用開發安裝

# 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

Stdio 模式的主要功能：

使用環境變數進行驗證（可透過 export 或 .env 檔案設定）
透過 stdin/stdout 直接通訊
特定 MCP 用戶端設定所需

工具類別

您可以僅啟用所需的工具與提示類別，以最佳化 server 效能：

使用 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

SSL 憑證驗證

對外發出 Instana API 呼叫的 SSL 憑證驗證預設為啟用。這適用於 Streamable HTTP 與 Stdio 兩種傳輸模式。

若要停用 SSL 憑證驗證（例如針對使用自簽或內部憑證的環境），請使用 --verify-ssl CLI 選項、INSTANA_SSL_VERIFY 環境變數，或 config.yaml 中的 sslVerify 鍵。

使用 CLI 選項

# Disable SSL verification
uv run src/core/server.py --verify-ssl false

# Explicitly enable (default behaviour, no flag needed)
uv run src/core/server.py --verify-ssl true

使用環境變數

export INSTANA_SSL_VERIFY=false
uv run src/core/server.py

當 INSTANA_SSL_VERIFY 設為 0、false 或 no（不區分大小寫）時，SSL 驗證會被停用。任何其他值，或當該變數未設定時，驗證會保持啟用。

使用 config.yaml（SaaS / Kubernetes 部署）

# SSL verification for outbound API calls (default: true)
sslVerify: false

sslVerify 鍵會在啟動時由 start.sh 讀取，並匯出為 INSTANA_SSL_VERIFY。

使用自訂 CA 憑證包

當 SSL 驗證啟用時，預設會使用系統 CA 憑證包。若要使用自訂 CA 憑證包，請設定 INSTANA_CA_BUNDLE：

export INSTANA_SSL_VERIFY=true
export INSTANA_CA_BUNDLE=/path/to/ca-bundle.crt
uv run src/core/server.py

INSTANA_CA_BUNDLE 僅在 SSL 憑證驗證啟用時使用。

伺服器會在啟動時記錄實際生效的 SSL 驗證狀態，因此您可以立即確認您的環境變數、CLI 旗標或設定檔設定是否已被採用。

API 呼叫逾時

每個對外的 Instana API 呼叫都受硬性實際時間逾時限制。如果 Instana 伺服器未在期限內回應，該呼叫會被取消並立即傳回錯誤——不會有無限期掛起的請求。

預設逾時為 180 秒。可使用 INSTANA_API_TIMEOUT 環境變數覆寫：

export INSTANA_API_TIMEOUT=60   # 60-second deadline
uv run src/core/server.py

INSTANA_API_TIMEOUT 必須是正整數（秒）。非整數或非正值會被忽略，並改用 180 秒的預設值。

目錄回應快取

伺服器會在處理程序內快取目錄 API 回應（指標、標籤和外掛程式），以消除多餘的往返。目錄資料在單一租用戶內是穩定的——只有在部署新整合時才會變更——因此回應在單一伺服器處理程序的存續期間內可安全重複使用。

預設 TTL：30 分鐘。 每個租用戶 URL、方法和參數的唯一組合都會有各自獨立的快取槽。錯誤回應永遠不會被快取，因此暫時性的網路失敗不會污染儲存區。

已快取的目錄操作

網域	操作	快取鍵區分項
Application	取得指標目錄	—
Application	取得標籤目錄	`use_case`、`data_source`
Website	取得指標目錄	—
Website	取得標籤目錄	`beacon_type`、`use_case`
Mobile App	取得指標目錄	—
Mobile App	取得標籤目錄	`beacon_type`、`use_case`
Synthetic	取得指標目錄	—
Synthetic	取得標籤目錄	`use_case`
Infrastructure	取得指標目錄	`plugin`、`filter`
Infrastructure	取得標籤目錄	`plugin`

設定快取（stdio 模式）

在啟動伺服器前設定環境變數。在 stdio 模式下，這些是唯一會使用的值——使用 Bob 時不需要重新啟動，因為伺服器會自動重新啟動。

# Disable caching entirely
export INSTANA_CACHE_ENABLED=false
# Override TTL to 5 minutes (default: 1800)
export INSTANA_CACHE_TTL=300

當 INSTANA_CACHE_ENABLED 設為 false、0 或 no（不區分大小寫）時，會被視為停用。任何其他值會保持快取啟用。

設定快取（streamable-http 模式）

除了上述環境變數外，每個 HTTP 請求都可以透過標頭覆寫快取設定。每個請求的標頭優先於處理程序層級的預設值，因此可以在不重新啟動伺服器的情況下切換快取的開關。

instana-cache-enabled: false
instana-cache-ttl: 300

若要在您的 MCP 用戶端設定中持續設定快取標頭（例如 streamable-http 模式下的 .bob/mcp.json），請將它們與現有的 Instana 標頭一併加入：

{
  "mcpServers": {
    "Instana MCP Server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "instana-cache-enabled": "true",
        "instana-cache-ttl": "1800"
      }
    }
  }
}

若要為特定用戶端連線停用快取：

{
  "mcpServers": {
    "Instana MCP Server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "instana-cache-enabled": "false"
      }
    }
  }
}

使用 .bob/mcp.json（stdio 模式）

若要為 Bob 持續設定快取組態，請將環境變數加入 .bob/mcp.json 中的 env 區塊：

{
  "mcpServers": {
    "instana": {
      "env": {
        "INSTANA_CACHE_ENABLED": "true",
        "INSTANA_CACHE_TTL": "1800"
      }
    }
  }
}

伺服器會在每次目錄呼叫時以 DEBUG 層級記錄實際生效的快取狀態，顯示回應是快取 HIT 還是 MISS。

驗證伺服器狀態

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

針對 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 / 憑證問題： 請參閱上方的 SSL 憑證驗證章節以了解設定選項。如果您在啟用驗證時遇到 SSL 錯誤且使用 macOS，請確保您的 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

設定與使用

支援的 MCP 用戶端

用戶端	傳輸方式
Bob IDE	`streamable http`、`stdio`
Bob CLI	`streamable http`、`stdio`
Claude Desktop	`streamable http`、`stdio`
Cursor IDE	`streamable http`、`stdio`
Kiro IDE	`streamable http`、`stdio`
Kiro CLI	`streamable http`、`stdio`
Github Copilot	`streamable http`、`stdio`
Copilot CLI	`streamable http`、`stdio`
Mistral AI	`streamable http`
Gemini Cli	`streamable http`、`stdio`

連線至多個 Instana MCP 伺服器

您可以設定 MCP 用戶端以連線至多個執行個體。以下為範例設定：

{
  "mcpServers": {
    "Instana MCP Server1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header",
        "instana-base-url: ENV1_INSTANA_URL",
        "--header",
        "instana-api-token: ENV1_INSTANA_API_TOKEN"
      ]
    },
    "Instana MCP Server2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header",
        "instana-base-url: ENV2_INSTANA_URL",
        "--header",
        "instana-api-token: ENV2_INSTANA_API_TOKEN"
      ]
    }
  }
}

若要指定特定伺服器，請確保：

伺服器在 MCP 設定中已使用適當的環境名稱進行設定（例如 Instana MCP Server1）
提示中明確提及伺服器/環境名稱。

請求接著會被路由至對應的已設定伺服器。如果提示中未明確提及任何伺服器/環境，MCP 會使用設定中定義的第一個伺服器作為預設伺服器。

注意：如果請求的伺服器已停止或無法連線，MCP 會如預期般運作並轉送 API 失敗。使用者會收到 API 傳回的對應錯誤，表示伺服器無法使用。MCP 依賴底層 API 的可用性，不會執行自動容錯移轉。

可用工具

工具	類別	說明
`manage_applications`	Application & Infrastructure	用於管理應用程式指標、警示設定、設定與目錄的統一工具
`manage_websites`	Website Monitoring	用於網站分析、目錄、設定與進階設定操作的統一智慧路由器
`manage_custom_dashboards`	Custom Dashboards	用於管理自訂儀表板 CRUD 操作的統一工具
`manage_infrastructure`	Infrastructure	用於基礎架構分析、目錄（`get_plugin_schema`）、智慧警示設定與快照資源操作的統一智慧路由器
`manage_automation`	Automation	用於自動化的統一智慧路由器：瀏覽動作目錄並檢視執行歷史記錄
`manage_events`	Events	用於事件監控的統一智慧路由器：依 ID 取得事件、依 ID 取得多個事件、Kubernetes 事件、代理程式監控事件與所有事件
`manage_slo`	SLO Management	用於 SLO 設定、報告、警示與修正時間窗的統一智慧路由器，具備智慧時區處理
`manage_releases`	Release Management	用於版本追蹤的統一智慧路由器：以分頁與名稱篩選列出發行版本、取得發行版本詳細資料、建立/更新/刪除發行版本並支援時區
`manage_maintenance_windows`	Maintenance Windows	用於維護時間窗生命週期管理的統一智慧路由器：建立、修改、關閉與列出維護時間窗，支援範本與 ServiceNow 整合
`manage_mobile_apps`	Mobile App Monitoring	用於行動應用程式監控的統一智慧路由器：分析信標、效能指標、工作階段重播、設定與警示管理
`manage_synthetics`	Synthetic Monitoring	用於合成監控的統一智慧路由器：目錄、指標、設定（唯讀）與測試播放結果

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

工具篩選

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

使用範例

使用 CLI（PyPI 安裝）

# Enable only application monitoring tools
mcp-instana --tools app --transport streamable-http

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

# Enable application and infrastructure tools
mcp-instana --tools app,infra --transport streamable-http

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

# Enable settings (custom dashboards) and app tools
mcp-instana --tools settings,app --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,events --transport streamable-http

# Enable automation and app tools
mcp-instana --tools automation,app --transport streamable-http

# Enable SLO management tools
mcp-instana --tools slo --transport streamable-http

# Enable synthetic monitoring tools
mcp-instana --tools synthetic --transport streamable-http

# Enable mobile app monitoring tools
mcp-instana --tools mobile_app --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 application monitoring tools
uv run src/core/server.py --tools app --transport streamable-http

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

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

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

# Enable custom_dashboards and application tools
uv run src/core/server.py --tools custom_dashboards,app --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,events --transport streamable-http

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

# Enable SLO management tools
uv run src/core/server.py --tools slo --transport streamable-http

# Enable synthetic monitoring tools
uv run src/core/server.py --tools synthetic --transport streamable-http

# Enable mobile app monitoring tools
uv run src/core/server.py --tools mobile_app --transport streamable-http

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

# Disable specific categories (all others remain enabled)
uv run src/core/server.py --transport streamable-http --omit-tools maintenance_windows,slo

# Combine --tools and --omit-tools
uv run src/core/server.py --transport streamable-http --tools app,infra,events --omit-tools events


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

Stdio 模式下的工具篩選

在 stdio 模式下，MCP 用戶端會將伺服器作為子處理程序啟動，因此旗標會透過 mcp.json 中的 args 陣列直接傳遞。

使用 --tools（允許清單）——僅顯示列出的類別：

{
  "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"
      }
    }
  }
}

使用 --omit-tools（拒絕清單）——顯示除列出類別以外的所有內容：

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

同時使用兩者——先選取子集，再從中移除：

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

透過 HTTP 標頭進行工具篩選（Streamable HTTP 模式）

當伺服器以 streamable HTTP 模式執行時，每個 MCP 用戶端都可以控制其看到的工具類別，而無需重新啟動伺服器或執行個別執行個體。支援兩個互補的標頭：

標頭	行為
`select-tools`	允許清單——僅顯示列出的類別
`omit-tools`	拒絕清單——顯示除列出類別以外的所有內容

兩個標頭都接受以逗號分隔的類別名稱清單，與 --tools / --omit-tools CLI 旗標所使用的名稱相同。它們可以合併使用：先套用 select-tools 建立可見集合，再由 omit-tools 從中移除。

使用 `select-tools`（允許清單）

僅顯示指定的類別：

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "select-tools": "infra,events"
      }
    }
  }
}

使用 `omit-tools`（拒絕清單）

顯示除指定類別以外的所有內容——當您想要大多數工具但需要隱藏一兩個時很有用：

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "omit-tools": "maintenance_windows,slo"
      }
    }
  }
}

合併兩個標頭

先選取子集，再從中移除：

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "select-tools": "app,infra,events,website",
        "omit-tools": "website"
      }
    }
  }
}

伺服器會在每次請求時為該用戶端連線篩選 tools/list 回應——連線至同一伺服器處理程序的所有其他用戶端不受影響。

未知的類別名稱會記錄為警告並被靜默忽略。
如果兩個標頭皆不存在，則會傳回所有已註冊的工具（預設行為）。
這些標頭在 stdio 模式下無效——請改用 --tools / --omit-tools CLI 旗標。

工具篩選的優點

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

如需使用範例與提示，請參閱範例提示

Docker 部署

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

建置 Docker 映像

先決條件

已安裝並執行 Docker
可存取專案原始碼

建置與執行

# Ensure you are in the mcp-instana directory of your repo
# Build the optimized production image
docker build -t mcp-instana:latest .

上述命令會使用 Dockerfile 中的指示來建置映像。預設連接埠為 8080，傳輸模式為 streamable-http

# Run the container (credentials are supplied via HTTP headers at request time)
docker run -p 8080:8080 mcp-instana

如果您想在主機上使用自訂連接埠（例如：9000）

# Run with a custom host port
docker run -p 9000:8080 mcp-instana

以可串流模式連線至 mcp-instana 容器

假設您使用以下命令啟動容器：docker run -p 8080:8080 mcp-instana

您的 MCP 用戶端會連線至主機連接埠（8080）。根據預設，容器會以可串流模式執行。

以下是 MCP 用戶端的範例設定：

{
  "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"
      ]
    }
  }
}

以 stdio 模式連線至 mcp-instana

在 stdio 模式下，您可以讓 MCP 用戶端啟動並連線至容器。在此您會透過為 --transport 旗標提供值，明確指定以 stdio 執行。

以下是範例設定：

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

如需更多詳細資訊，請參閱 Docker 部署指南這裡

如需完整的 Docker 文件，包括多架構建置、.dockerignore、安全性最佳實務與生產部署範例，請參閱 DOCKER.md。

一般問題

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 憑證並確保其為最新狀態。

IBM Instana MCP Server

你可以用 IBM Instana MCP 做什麼？

文件

目錄

IBM Instana MCP Server

快速連結

架構概觀

工作流程

先決條件

安裝 Instana MCP server

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

選項 2：開發安裝

安裝 uv

設定環境

Streamable HTTP 模式的標頭式驗證

1. API Token 驗證（直接 API 呼叫）

2. Session Token 驗證（由 UI 發起的呼叫）

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

啟動本機 MCP Server

Server 指令選項

使用 CLI（PyPI 安裝）

使用開發安裝

以 Streamable HTTP 模式啟動

使用 CLI（PyPI 安裝）

使用開發安裝

以 Stdio 模式啟動

使用 CLI（PyPI 安裝）

使用開發安裝

工具類別

使用 CLI（PyPI 安裝）

使用開發安裝

SSL 憑證驗證

使用 CLI 選項

使用環境變數

使用 config.yaml（SaaS / Kubernetes 部署）

使用自訂 CA 憑證包

API 呼叫逾時

目錄回應快取

已快取的目錄操作

設定快取（stdio 模式）

設定快取（streamable-http 模式）

使用 .bob/mcp.json（stdio 模式）

驗證伺服器狀態

常見啟動問題

設定與使用

支援的 MCP 用戶端

連線至多個 Instana MCP 伺服器

可用工具

工具篩選

使用範例

使用 CLI（PyPI 安裝）

使用開發安裝

Stdio 模式下的工具篩選

透過 HTTP 標頭進行工具篩選（Streamable HTTP 模式）

使用 select-tools（允許清單）

使用 omit-tools（拒絕清單）

合併兩個標頭

工具篩選的優點

Docker 部署

建置 Docker 映像

先決條件

建置與執行

以可串流模式連線至 mcp-instana 容器

以 stdio 模式連線至 mcp-instana

一般問題

使用 `select-tools`（允許清單）

使用 `omit-tools`（拒絕清單）