IBM Instana MCP Server

官方

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

GitHub

试用此 MCP赞助

你可以用 IBM Instana MCP 做什么？

查询应用性能 — 使用 app 类别的工具（如 get_app_metrics 或 get_app_alerts）请求应用指标、警报或目录详情。
监控基础设施健康 — 通过 infra 工具（如 get_infra_metrics 或 get_infra_topology）检索基础设施资源、拓扑和指标。
跟踪事件和事件 — 使用 events 工具（如 get_k8s_events 或 get_agent_status）访问 Kubernetes 事件或代理监控数据。
分析网站监控 — 使用 website 工具（如 get_website_metrics 或 get_website_config）拉取网站指标、目录信息或配置。
按类别筛选工具 — 启动时使用 --tools 标志仅启用所需的工具类别（例如 --tools infra,events）以优化性能。

文档

IBM Instana 的 MCP 服务器

📚 快速链接

工具与示例 - 包含真实世界示例的全面工具文档
隐私政策 - 数据处理与隐私信息
Docker 部署指南 - 全面的 Docker 部署、多架构构建和生产环境设置

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 告警的信息时，将发生以下过程：

MCP 客户端从 Instana MCP 服务器检索可用工具列表
您的查询连同工具描述一起发送到 LLM
LLM 分析可用工具并选择合适的工具来检索 Instana 告警
客户端通过 Instana MCP 服务器执行所选工具
结果（最新告警）返回给 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

前提条件

选项 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"
      ]
    }
  }
}

认证优先级：

JWT 令牌（如果提供 CSRF 令牌）- 优先用于 IBM 平台集成
会话令牌（如果同时提供 auth_token 和 csrf_token）
API 令牌（如果提供）- 标准认证
环境变量（INSTANA_API_TOKEN）- 回退选项

认证流程：

每个请求中必须存在 HTTP 标头
服务器根据优先级顺序验证凭据
没有有效认证的请求将失败

此设计确保凭据的安全传输，并支持多种认证流程，包括通过 WebSocket → Coordinator → MCP Server 的 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 启用基础设施工具和所有与基础设施相关的提示词。
--list-tools：列出所有可用的工具类别并退出
--port <port>：MCP 服务器端口（默认：8080，可通过 PORT 环境变量覆盖）
--verify-ssl：为出站 Instana API 调用启用 SSL 证书验证。等同于设置 INSTANA_SSL_VERIFY=true。SSL 验证默认禁用。
--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：网站监控工具和提示词（指标、目录、分析、配置）

SSL 证书验证

出站 Instana API 调用的 SSL 证书验证默认禁用。这适用于 Streamable HTTP 和 Stdio 两种传输模式。

要启用 SSL 证书验证，请使用 --verify-ssl CLI 选项或 INSTANA_SSL_VERIFY 环境变量。

使用 CLI 选项

uv run src/core/server.py --verify-ssl

--verify-ssl 选项等同于设置：

export INSTANA_SSL_VERIFY=true

使用环境变量

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

当 INSTANA_SSL_VERIFY 设置为 0、false 或 no（不区分大小写）时，SSL 验证将被禁用；如果该变量未设置，同样会禁用 SSL 验证。任何其他值都会启用验证——请使用 true、1 或 yes 作为常规选择。

使用自定义 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 标志是否已被识别。

验证服务器状态

启动后，您可以验证服务器是否正在运行：

对于 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

设置与使用

Bob IDE

Bob 是 IBM 的 AI 驱动 IDE，原生支持 MCP 集成。Bob 提供无缝的开发体验，内置 AI 辅助和可观测性工具。

Streamable HTTP 模式

Streamable HTTP 模式通过基于 HTTP 的 JSON-RPC 为 MCP 通信提供 REST API 接口。

步骤 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 以连接到您的本地 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 以连接到远程 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"
      ]
    }
  }
}

注意： 如果您遇到“找不到命令”错误，请使用 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 模式通过基于 HTTP 的 JSON-RPC 为 MCP 通信提供 REST API 接口。

步骤 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 界面中看到 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（幽灵）图标以访问 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”按钮，您将看到您的 MCP 服务器及其可用工具出现在 Kiro 的左下角区域。 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 中管理服务器

打开 .vscode/mcp.json - 您将在顶部看到服务器管理控件
点击 Instana MCP Server 旁边的 Start 以启动服务器
运行状态以及工具数量表示服务器正在运行

步骤 3：测试集成

在 GitHub Copilot 中切换到 Agent 模式并重新加载工具。以下是 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

导航到左侧边栏中的 Intelligence 选项卡，然后选择 Connectors
点击 Add Connector
通过输入连接器名称和 Ngrok 转发的 MCP 服务器 URL 来创建自定义连接器
开始新的聊天会话并验证 MCP 工具已启用。您可以在此处查看响应

连接到多个 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`	应用与基础设施	用于管理应用指标、告警配置、设置和目录的统一工具
`manage_websites`	网站监控	用于网站分析、目录、配置和高级配置操作的统一智能路由器
`manage_custom_dashboards`	自定义仪表板	用于管理自定义仪表板 CRUD 操作的统一工具
`manage_infrastructure`	基础设施	用于基础设施分析、目录（`get_plugin_schema`）和快照资源操作的统一智能路由器
`manage_automation`	自动化	用于自动化的统一智能路由器：浏览操作目录和查看执行历史
`manage_events`	事件	用于事件监控的统一智能路由器：按 ID 获取事件、按 ID 列表获取事件、Kubernetes 事件、代理监控事件和所有事件
`manage_slo`	SLO 管理	用于 SLO 配置、报告、告警和修正窗口的统一智能路由器，支持智能时区处理
`manage_releases`	发布管理	用于发布跟踪的统一智能路由器：带分页和名称过滤的发布列表、获取发布详情、创建/更新/删除发布并支持时区
`manage_maintenance_windows`	维护窗口	用于维护窗口生命周期管理的统一智能路由器：创建、修改、关闭和列出维护窗口，支持模板和 ServiceNow 集成
`manage_mobile_apps`	移动应用监控	用于移动应用监控的统一智能路由器：分析信标、性能指标、会话回放、配置和告警管理
`manage_synthetics`	综合监控	用于综合监控的统一智能路由器：目录、指标、设置（只读）和测试回放结果

👉 有关详细的工具文档、功能和技术参考，请参阅工具与示例

工具过滤

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 掩码设置
- 告警管理：配置和管理移动应用告警配置
synthetics：综合监控管理
- manage_synthetics：用于所有综合监控操作的统一智能路由器
- 目录：在构建查询之前发现有效的指标 ID 和标签名称
- 指标：按位置或测试名称分组检索聚合响应时间和成功率
- 设置：列出和查找测试及位置，自动解析名称；识别数据中心（托管）与自托管（私有）PoP
- 测试回放：每次运行的原始结果、LAST_VALUE 分析、按位置的成功率摘要以及详细文件下载（LOGS、HAR、截图）

使用示例

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

前提条件

已安装并运行 Docker
可访问项目源代码

构建和运行

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

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

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

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

📖 有关全面的 Docker 文档，包括多架构构建、.dockerignore、安全最佳实践和生产部署示例，请参阅 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 (expects 406 from a bare GET — means server is up)
curl http://localhost:8080/mcp
# 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 证书并确保它们是最新的。