IBM Instana MCP Server

官方

IBM Instana MCP服务器支持与IBM Instana可观测性平台无缝交互，使您能够直接在开发工作流中访问实时可观测性数据。

GitHub
24

你可以用 IBM Instana MCP 做什么？

  • 检索并分析 Instana 告警 — 使用 get_alerts 查询特定应用或服务的当前告警。
  • 查询基础设施指标与拓扑 — 通过 get_metrics 和 get_topology 获取 CPU、内存或磁盘指标，并探索资源关系。
  • 调查 Kubernetes 事件 — 借助 get_events 获取近期集群事件、警告或代理状态变更。
  • 监控网站性能 — 通过 get_website_metrics 和 get_website_configuration 拉取网站特定指标、分析页面加载或查看网站配置。
  • 发现受监控的应用与服务 — 使用 get_applications 和 get_catalog 列出 Instana 实例中的应用、端点或目录条目。

文档

目录

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 辅助和可观测性工具。

流式 HTTP 模式

流式 HTTP 模式提供了一个 REST API 接口，用于通过 HTTP 使用 JSON-RPC 进行 MCP 通信。

步骤 1：在流式 HTTP 模式下启动 MCP 服务器

在配置 Bob 之前，您需要在流式 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 服务器：

{
  "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 服务器（例如，部署在 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"
      ]
    }
  }
}

注意： 如果遇到“command not found”错误，请使用 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 支持流式 HTTP 和 Stdio 两种模式进行 MCP 集成。

通过编辑配置文件来配置 Claude Desktop：

文件位置：

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

流式 HTTP 模式

流式 HTTP 模式提供了一个 REST API 接口，用于通过 HTTP 使用 JSON-RPC 进行 MCP 通信。

步骤 1：在流式 HTTP 模式下启动 MCP 服务器

在配置 Claude Desktop 之前，您需要在流式 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 服务器，如下所示：

您现在可以在 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"
      ]
    }
  }
}

注意： 如果遇到“command not found”错误，请使用 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），并根据您首选的传输模式进行配置：

流式 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 的集成，请参阅此设置指南。

流式 HTTP 模式

步骤 1：在流式 HTTP 模式下启动 MCP 服务器

在配置 VS Code 之前，您需要在流式 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 仅通过流式 HTTP 模式支持 MCP 集成。

步骤 1：在流式 HTTP 模式下启动 MCP 服务器

通过提供您的 Instana 凭据，在流式 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)
    • 应用指标
      • 使用灵活过滤查询应用指标
      • 列出服务和端点
      • 按标签分组并聚合指标
    • 应用告警配置
      • 查找活跃的告警配置
      • 获取告警配置版本
      • 创建、更新和删除告警配置
      • 启用、禁用和恢复告警配置
      • 更新历史基线
    • 全局应用告警配置
      • 管理全局告警配置
      • 全局告警的版本控制
    • 应用设置
      • 管理应用视角
      • 配置端点和服​​务
      • 管理手动服务
    • 应用目录
      • 获取应用标签目录
      • 获取应用指标目录
  • 基础设施管理 (manage_infrastructure)
    • 统一智能路由器，取代 analyze_infrastructure — 用于分析、目录和资源快照的单一工具
    • get_plugin_schema — 在一次 API 调用中获取插件的指标和标签（取代两次单独调用）
    • 动态支持 Instana API 目录中的所有实体类型（JVM、Kubernetes、Docker、主机、数据库、消息队列等）
    • 移除静态模式文件 — 所有模式均从 Instana API 实时获取
    • 快照资源操作：get_snapshot、get_snapshots
    • 灵活的指标聚合（最大值、平均值、总和等）
    • 按标签和属性进行高级过滤
    • 分组和排序功能
    • 时间范围查询
  • 统一事件管理 (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_mobile_apps)
    • 会话回放 — 新增 (resource_type="session_replay")
      • get_session_replay_action_beacons — 按移动应用 ID 和会话 ID 分页检索操作信标
      • 基于游标的分页 (cursor、page_size、hasMore)
    • 信标分析、性能指标、地理与设备分析、告警管理（现有）
  • 统一网站管理 (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 操作的综合工具
manage_infrastructure基础设施用于基础设施分析、目录 (get_plugin_schema) 和快照资源操作的综合智能路由器
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：基础设施管理工具

    • manage_infrastructure：用于基础设施分析、目录和快照资源操作的综合智能路由器
    • get_plugin_schema 将 get_metrics + get_tag_catalog 合并到单个 API 调用中
    • 动态支持 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：用于移动应用监控操作的统一智能路由器
    • 会话回放：按移动应用 ID 和会话 ID 检索分页的会话回放操作信标（resource_type="session_replay"）
    • 信标分析：通过分组和过滤查询移动应用信标数据
    • 性能指标：跟踪会话持续时间、崩溃率和 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 证书并确保它们是最新的。