Labsco
instana logo

IBM Instana MCP Server

★ 22

from instana

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

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#devops#git#maps#security#monitoring
<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

MCP Server for IBM Instana

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. For more details, refer to the MCP Transport Modes specification.

Architecture Overview

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

Workflow

Consider a simple example: You're using an MCP Host (such as Claude Desktop, VS Code, or another client) connected to the Instana MCP Server. When you request information about Instana alerts, the following process occurs:

  1. The MCP client retrieves the list of available tools from the Instana MCP server
  2. Your query is sent to the LLM along with tool descriptions
  3. The LLM analyzes the available tools and selects the appropriate one(s) for retrieving Instana alerts
  4. The client executes the chosen tool(s) through the Instana MCP server
  5. Results (latest alerts) are returned to the LLM
  6. The LLM formulates a natural language response
  7. The response is displayed to you
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

Starting the Local MCP Server

Before configuring any MCP client (Claude Desktop, GitHub Copilot, or custom MCP clients), you need to start the local MCP server. The server supports two transport modes: Streamable HTTP and Stdio.

Server Command Options

Using the CLI (PyPI Installation)

If you installed mcp-instana from PyPI, use the mcp-instana command:

mcp-instana [OPTIONS]

Using Development Installation

For local development, use the uv run command:

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

Available Options:

  • --transport <mode>: Transport mode (choices: streamable-http, stdio)
  • --env KEY=VALUE: Set environment variable (can be repeated for multiple variables, e.g., --env INSTANA_BASE_URL=https://... --env INSTANA_API_TOKEN=...)
  • --debug: Enable debug mode with additional logging
  • --log-level <level>: Set the logging level (choices: DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • --tools <categories>: Comma-separated list of tool categories to enable (e.g., infra,app,events,website). Enabling a category will also enable its related prompts. For example: --tools infra enables the infra tools and all infra-related prompts.
  • --list-tools: List all available tool categories and exit
  • --port <port>: MCP server port (default: 8080, can be overridden with PORT env var)
  • --help: Show help message and exit

Starting in Streamable HTTP Mode

Streamable HTTP mode provides a REST API interface and is recommended for most use cases.

Using CLI (PyPI Installation)

# 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

Using Development Installation

# 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

Key Features of Streamable HTTP Mode:

  • Uses HTTP headers for authentication (no environment variables needed)
  • Supports different credentials per request
  • Better suited for shared environments
  • MCP server default port: 8080
  • MCP endpoint: http://0.0.0.0:8080/mcp/

Starting in Stdio Mode

Stdio mode uses standard input/output for communication and requires environment variables for authentication.

Using CLI (PyPI Installation)

# 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

Using Development Installation

# 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

Key Features of Stdio Mode:

  • Uses environment variables for authentication (can be set via export or --env flag)
  • Direct communication via stdin/stdout
  • Required for certain MCP client configurations
  • The --env flag provides a convenient way to set credentials without modifying shell environment

Tool Categories

You can optimize server performance by enabling only the tools and prompts categories you need:

Using CLI (PyPI Installation)

# 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

Using Development Installation

# 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

Available Categories:

  • infra: Infrastructure monitoring tools and prompts (resources, catalog, topology, analyze, metrics)
  • app: Application performance tools and prompts (resources, metrics, alerts, catalog, topology, analyze, settings, global alerts)
  • events: Event monitoring tools and prompts (Kubernetes events, agent monitoring)
  • website: Website monitoring tools and prompts (metrics, catalog, analyze, configuration)

Verifying Server Status

Once started, you can verify the server is running:

For Streamable HTTP mode:

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

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

For Stdio mode: The server will start and wait for stdin input from MCP clients.

Common Startup Issues

Certificate Issues: If you encounter SSL certificate errors, ensure your Python environment has access to system certificates:

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

Port Already in Use: If port 8080 is already in use, specify a different port:

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

Missing Dependencies: Ensure all dependencies are installed:

uv sync

Supported Features

  • Unified Application & Infrastructure Management (manage_instana_resources)
    • Application Metrics
      • Query application metrics with flexible filtering
      • List services and endpoints
      • Group by tags and aggregate metrics
    • Application Alert Configuration
      • Find active alert configurations
      • Get alert configuration versions
      • Create, update, and delete alert configurations
      • Enable, disable, and restore alert configurations
      • Update historic baselines
    • Global Application Alert Configuration
      • Manage global alert configurations
      • Version control for global alerts
    • Application Settings
      • Manage application perspectives
      • Configure endpoints and services
      • Manage manual services
    • Application Catalog
      • Get application tag catalog
      • Get application metric catalog
  • Infrastructure Analysis (analyze_infrastructure)
    • Two-pass elicitation for entity/metric queries
    • Dynamic support for all entity types from Instana API catalog (JVM, Kubernetes, Docker, hosts, databases, message queues, and more)
    • Automatically synchronized with your Instana installation's available plugins
    • Flexible metric aggregation (max, mean, sum, etc.)
    • Advanced filtering by tags and properties
    • Grouping and ordering capabilities
    • Time range queries
  • Unified Events Management (manage_events)
    • Events Monitoring
      • Get Event by ID (operation="get_event")
      • Get Events by IDs (operation="get_events_by_ids")
      • Get Agent Monitoring Events (operation="get_agent_monitoring_events")
      • Get Kubernetes Info Events (operation="get_kubernetes_info_events")
      • Get Events (operation="get_events")
    • Smart routing to specialized event tools
    • Unified parameter validation (time ranges, max_events)
    • Support for natural language time ranges ("last 24 hours", "last 2 days")
    • Event filtering and optimization
  • Unified Website Management (manage_website_resources)
    • Website Analyze (resource_type="analyze")
      • Get Website Beacon Groups - grouped/aggregated beacon data (operation="get_beacon_groups")
      • Get Website Beacons - individual beacon data with pagination (operation="get_beacons")
      • Automatic tag validation and catalog-based elicitation workflow
      • Response summarization (70-80% payload reduction)
      • Support for multiple beacon types: PAGELOAD, PAGECHANGE, RESOURCELOAD, CUSTOM, HTTPREQUEST, ERROR
    • Website Catalog (resource_type="catalog")
      • Get Website Metrics Catalog (operation="get_metrics")
      • Get Website Tag Catalog by beacon type and use case (operation="get_tag_catalog")
    • Website Configuration (resource_type="configuration")
      • Get All Websites (operation="get_all")
      • Get Website by ID or name with automatic name resolution (operation="get")
    • Advanced Configuration - READ ONLY (resource_type="advanced_config")
      • Get Geo-Location Configuration (operation="get_geo_config")
      • Get IP Masking Configuration (operation="get_ip_masking")
      • Get Geo Mapping Rules (operation="get_geo_rules")
  • Unified Automation Management (manage_automation)
    • Action Catalog (resource_type="catalog")
      • List all available automation actions (operation="get_actions")
      • Get detailed information about a specific action (operation="get_action_details")
      • Search for matching actions by name/description (operation="get_action_matches")
      • Get action matches by application or snapshot ID and time window (operation="get_action_matches_by_id_and_time_window")
      • Get available action types (operation="get_action_types")
      • Get available action tags (operation="get_action_tags")
    • Action History (resource_type="history")
      • List action execution instances with filtering (operation="list")
      • Get details of a specific action execution (operation="get_details")
  • Custom Dashboards (manage_custom_dashboards)
    • Get all custom dashboards
    • Get specific dashboard by ID
    • Create new custom dashboard
    • Update existing custom dashboard
    • Delete custom dashboard
    • Get shareable users for dashboard
    • Get shareable API tokens for dashboard

Available Tools

ToolCategoryDescription
manage_applicationsApplication & InfrastructureUnified tool for managing application metrics, alert configs, settings, and catalog
manage_websitesWebsite MonitoringUnified smart router for website analyze, catalog, configuration, and advanced config operations
manage_custom_dashboardsCustom DashboardsUnified tool for managing custom dashboard CRUD operations
analyze_infrastructureInfrastructure AnalyzeTwo-pass infrastructure analysis with entity/metric elicitation
manage_automationAutomationUnified smart router for automation: browse action catalog and view execution history
manage_eventsEventsUnified smart router for events monitoring: get event by ID, get events by IDs, Kubernetes events, agent monitoring events and all events
manage_sloSLO ManagementUnified smart router for SLO configurations, reports, alerts, and correction windows with intelligent timezone handling
manage_releasesRelease ManagementUnified smart router for release tracking: list releases with pagination and name filtering, get release details, create/update/delete releases with timezone support
manage_maintenance_windowsMaintenance WindowsUnified smart router for maintenance window lifecycle management: create, modify, close, and list maintenance windows with template support and ServiceNow integration
manage_mobile_appsMobile App MonitoringUnified smart router for mobile app monitoring: analyze beacons, performance metrics, configuration, and alert management

👉 For detailed tool documentation, capabilities, and technical reference, see Tools & Examples

Tool Filtering

The MCP server supports selective tool loading to optimize performance and reduce resource usage. You can enable only the tool categories you need for your specific use case.

Available Tool Categories

  • router: Unified application and infrastructure management

    • manage_instana_resources: Single tool for application metrics, alert configurations, settings, and catalog
    • Supports application perspectives, endpoints, services, and manual services
    • Manages both application-specific and global alert configurations
    • Provides access to application tag catalog and metric catalog

  • dashboard: Custom dashboard management

    • manage_custom_dashboards: CRUD operations for custom dashboards
    • Supports dashboard creation, retrieval, updates, and deletion
    • Manages shareable users and API tokens for dashboards

  • infra: Infrastructure analysis tools

    • analyze_infrastructure: Two-pass infrastructure analysis with entity/metric elicitation
    • Dynamically supports all entity types available in your Instana installation (automatically loaded from API catalog)
    • Includes JVM, Kubernetes, Docker, hosts, databases, message queues, and any custom or newly added entity types
    • Flexible metric aggregation, filtering, grouping, and time range queries

  • automation: Automation action tools

    • manage_automation: Unified smart router for automation catalog and execution history
    • Action Catalog: browse actions, get details, search by name/description, filter by application or snapshot ID
    • Action History: list execution instances with filtering, get execution details

  • events: Event monitoring tools

    • Events: Kubernetes events, agent monitoring and system event tracking

  • website: Website monitoring tools

    • Website Metrics: Performance measurement for websites
    • Website Catalog: Website metadata and definitions
    • Website Analyze: Website performance analysis
    • Website Configuration: Website configuration management

  • slo: Service Level Objective (SLO) management

    • manage_slo: Unified smart router for comprehensive SLO operations
    • Configuration Management: Create, read, update, delete SLO configurations with support for time-based and event-based indicators
    • Report Generation: Generate detailed SLO reports with SLI values, error budgets, burn rates, and time-series charts
    • Alert Configuration: Manage SLO alert configs for error budget monitoring and burn rate tracking
    • Correction Windows: Create and manage maintenance windows to exclude planned downtime from SLO calculations
    • Intelligent Timezone Handling: Automatic timezone elicitation for datetime inputs to ensure accurate time context
    • Two-Pass Elicitation: Interactive parameter gathering for complex operations requiring multiple inputs

  • releases: Release tracking and deployment management

    • manage_releases: Unified smart router for release operations
    • List Releases: Get all releases with efficient pagination (page_number, page_size) and name-based filtering
    • Release Details: Retrieve specific release information by ID including applications, services, and scopes
    • Create/Update/Delete: Full CRUD operations for release management
    • Intelligent Timezone Handling: Automatic timezone elicitation for release start times
    • Efficient Pagination: Avoid redundant data fetching with proper page-based navigation
    • Name Filtering: Case-insensitive substring matching to find releases by name

  • maintenance_window: Maintenance window lifecycle management

    • manage_maintenance_windows: Unified smart router for maintenance window operations
    • Window Operations: Create, modify, close, and list maintenance windows (active, scheduled, all, expired)
    • Bulk Operations: Create maintenance windows for multiple applications simultaneously
    • Template Support: Predefined templates for common scenarios (deployment, database_migration, infrastructure_upgrade, emergency, routine)
    • Recurring Windows: Support for recurring maintenance windows using RFC 5545 RRULE format
    • ServiceNow Integration: Optional integration with ServiceNow change requests
    • Validation: Parameter validation before window creation
    • Flexible Duration: Specify duration in minutes, hours, or days

  • mobile_app: Mobile application monitoring

    • manage_mobile_apps: Unified smart router for mobile app monitoring operations
    • Beacon Analysis: Query mobile app beacon data with grouping and filtering
    • Performance Metrics: Track session duration, crash rates, and HTTP request performance
    • Geographic Analysis: Analyze user distribution by country, city, and region
    • Device Analysis: Monitor performance across different devices, platforms, and OS versions
    • Configuration Management: Manage mobile app configurations, geo-location, and IP masking settings
    • Alert Management: Configure and manage mobile app alert configurations

Usage Examples

Using CLI (PyPI Installation)

# 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

Using Development Installation

# 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

Benefits of Tool Filtering

  • Performance: Reduced startup time and memory usage
  • Security: Limit exposure to only necessary APIs
  • Clarity: Focus on specific use cases (e.g., only infrastructure monitoring)
  • Resource Efficiency: Lower CPU and network usage

👉 For usage examples and prompts, see Example Prompts