IBM Instana MCP Server¶

Overview¶

The Instana MCP server is built as a comprehensive wrapper around Instana's public REST APIs. It translates conversational queries into precise API calls and formats responses for AI assistants.

The Instana MCP server enables seamless interaction with the Instana observability platform, allowing you to access real-time observability data directly within your development workflow.

It serves as a bridge between clients (such as AI agents or custom tools) and the Instana REST APIs, converting user queries into Instana API requests and formatting the responses into structured, easily consumable formats.

The server supports both Streamable HTTP and Stdio transport modes for maximum compatibility with different MCP clients.

Features¶

• Comprehensive API coverage: Access to Instana's complete REST API suite, including metrics retrieval, resource discovery, alert management, and infrastructure analysis.
• Intelligent query processing: Features automatic parameter validation, pagination handling, response formatting, and contextual error messaging optimized for AI interactions.
• Flexible filtering: Offers advanced filtering options, such as, time-based queries, tag-based searches, metric thresholds, and text-based discovery across your observability stack.
• Natural language interface: Each tool is designed to understand conversational queries such as: "Show me applications with high error rates in the last hour" "What infrastructure plugins are available for monitoring databases?" "List all active alert configurations for our production services."

Prerequisites - IBM Instana setup, API tokens, required permissions¶

Option 1: Install from PyPI (Recommended)¶

The easiest way to use mcp-instana is to install it directly from PyPI:

pip install mcp-instana

After installation, you can run the server using the mcp-instana command directly.

Option 2: Development Installation¶

For development or local customization, you can clone and set up the project locally.

Installing uv¶

This project uses uv, a fast Python package installer and resolver. To install uv, you have several options:

Using pip¶

pip install uv

Using Homebrew (macOS)¶

brew install uv

For more installation options and detailed instructions, visit the uv documentation.

Setting Up the Environment¶

After installing uv, set up the project environment by running:

uv sync

Header-Based Authentication for Streamable HTTP Mode¶

When using Streamable HTTP mode, you must pass Instana credentials via HTTP headers. This approach enhances security and flexibility by:

• Avoiding credential storage in environment variables
• Enabling the use of different credentials for different requests
• Supporting shared environments where environment variable modification is restricted

Required Headers¶

• instana-base-url: Your Instana instance URL
• instana-api-token: Your Instana API token

Authentication Flow¶

HTTP headers (instana-base-url, instana-api-token) must be present in each request Requests without these headers will fail This design ensures secure credential transmission where credentials are only sent via headers for each request, making it suitable for scenarios requiring different credentials or avoiding credential storage in environment variables.

Server Configuration¶

Installation and Setup¶

TBD: Document server installation and setup steps.

Instana authentication configuration¶

TBD: Document Instana authentication configuration.

Monitoring scope setup¶

TBD: Document monitoring scope setup.

MCP Gateway Integration¶

Registration with MCP Gateway¶

TBD: Document registration with MCP Gateway.

Server configuration examples¶

TBD: Provide server configuration examples.

Available monitoring and inspection tools¶

TBD: List available monitoring and inspection tools.

Usage Examples¶

Claude Desktop Configuration¶

Claude Desktop supports both Streamable HTTP and Stdio modes for MCP integration.

Add to claude_desktop_config.json:

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

GitHub Copilot Configuration¶

You can directly create or update .vscode/mcp.json with the following configuration:

Step 1: Start the MCP Server in Streamable HTTP Mode

Before configuring VS Code, you need to start the MCP server in Streamable HTTP mode.

Step 2: Configure VS Code

You can directly create or update .vscode/mcp.json with the following configuration:

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

Application monitoring queries¶

TBD: Provide application monitoring query examples.

Infrastructure resource inspection¶

TBD: Document infrastructure resource inspection.

Performance analysis¶

TBD: Document performance analysis examples.

Alert and incident management¶

TBD: Document alert and incident management.

Troubleshooting¶

Authentication issues¶

TBD: Document common authentication issues and solutions.

API connectivity problems¶

TBD: Document API connectivity troubleshooting.

Data access permissions¶

TBD: Document data access permission issues.