IBM Instana MCP Server
About
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.
Details
- Author
- instana
- Categories
- Cloud Service, Infrastructure, Other
Jump to
Option 1: Install from PyPI (Recommended)
The easiest way to use mcp-instana is to install it directly from PyPI:
After installation, you can run the server using themcp-instanacommand directly.
For development or local customization, you can clone and set up the project locally.
This project usesuv, a fast Python package installer and resolver. To installuv, you have several options:
For more installation options and detailed instructions, visit the[uv documentation.
After installinguv, set up the project environment by running:
- Query application performance— Ask for application metrics, alerts, or catalog details usingappcategory tools likeget_app_metricsorget_app_alerts.
- Monitor infrastructure health— Retrieve infrastructure resources, topology, and metrics viainfratools such asget_infra_metricsorget_infra_topology.
- Track events and incidents— Access Kubernetes events or agent monitoring data witheventstools likeget_k8s_eventsorget_agent_status.
- Analyze website monitoring— Pull website metrics, catalog info, or configuration usingwebsitetools such asget_website_metricsorget_website_config.
- Filter tools by category— Enable only needed tool categories at startup with--toolsflag (e.g.,--tools infra,events) to optimize performance.
- 📚 Quick Links
- Architecture Overview
- Workflow
- Prerequisites
- Option 1: Install from PyPI (Recommended)
- Option 2: Development Installation
- Installing uv
- Setting Up the Environment
- 1. API Token Authentication (Direct API Calls)
- 2. Session Token Authentication (UI-Initiated Calls)
- 3. JWT Token Authentication (IBM Platform Integration)
- Using the CLI (PyPI Installation)
- Using Development Installation
- Using CLI (PyPI Installation)
- Using Development Installation
- Using CLI (PyPI Installation)
- Using Development Installation
- Using CLI (PyPI Installation)
- Using Development Installation
- Using the CLI option
- Using the environment variable
- Using a custom CA bundle
- Streamable HTTP Mode (Recommended for Kiro)
- Stdio Mode
- Available Tool Categories
- Usage Examples
- Using CLI (PyPI Installation)
- Using Development Installation
- Container Won't Start
- Connection Issues
- Performance Issues
- Tools & Examples- Comprehensive tool documentation with real-world examples
- Privacy Policy- Data handling and privacy information
- Docker Deployment Guide- Comprehensive Docker deployment, multi-architecture builds, and production setup
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 bothStreamable HTTPandStdiotransport modes for maximum compatibility with different MCP clients. For more details, refer to theMCP Transport Modes specification.
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
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:
- The MCP client retrieves the list of available tools from the Instana MCP server
- Your query is sent to the LLM along with tool descriptions
- The LLM analyzes the available tools and selects the appropriate one(s) for retrieving Instana alerts
- The client executes the chosen tool(s) through the Instana MCP server
- Results (latest alerts) are returned to the LLM
- The LLM formulates a natural language response
- 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
Option 1: Install from PyPI (Recommended)
The easiest way to use mcp-instana is to install it directly from PyPI:
After installation, you can run the server using themcp-instanacommand directly.
For development or local customization, you can clone and set up the project locally.
This project usesuv, a fast Python package installer and resolver. To installuv, you have several options:
For more installation options and detailed instructions, visit theuv documentation.
After installinguv, set up the project environment by running:
Header-Based Authentication for Streamable HTTP Mode
When usingStreamable 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
- Supporting both API token and session-based authentication
1. API Token Authentication (Direct API Calls)
- instana-base-url: Your Instana instance URL
- instana-api-token: Your Instana API token
--header "instana-base-url: https://your-instance.instana.io" --header "instana-api-token: your-api-token"
2. Session Token Authentication (UI-Initiated Calls)
3. JWT Token Authentication (IBM Platform Integration)
- instana-base-url: Your Instana instance URL
- instana-jwt-token: JWT token from IBM Platform
- instana-csrf-token: CSRF token for request validation
{ "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(if provided with CSRF token) - Takes precedence for IBM Platform integration
- Session Tokens(if both auth_token and csrf_token provided)
- API Token(if provided) - Standard authentication
- Environment Variable(INSTANA_API_TOKEN) - Fallback
- HTTP headers must be present in each request
- Server validates credentials based on priority order
- Requests without valid authentication will fail
This design ensures secure credential transmission and supports multiple authentication flows including UI-initiated calls via WebSocket → Coordinator → MCP Server.
Ensure that the token used has the necessary permissions to invoke MCP tools. Checkherefor more information.
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 HTTPandStdio.
If you installed mcp-instana from PyPI, use themcp-instanacommand:
For local development, use theuv runcommand:
- --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 infraenables 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)
- --verify-ssl: Enable SSL certificate verification for outgoing Instana API calls. Equivalent to settingINSTANA_SSL_VERIFY=true. SSL verification isdisabled by default.
- --help: Show help message and exit
Streamable HTTP modeprovides a REST API interface and is recommended for most use cases.
# 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
- 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/
Stdio modeuses standard input/output for communication and requires environment variables for authentication.
# 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
- Uses environment variables for authentication (can be set viaexportor--envflag)
- Direct communication via stdin/stdout
- Required for certain MCP client configurations
- The--envflag provides a convenient way to set credentials without modifying shell environment
You can optimize server performance by enabling only the tools and prompts categories you need:
# 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: 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)
SSL certificate verification for outgoing Instana API calls isdisabled by default. This applies to bothStreamable HTTPandStdiotransport modes.
To enable SSL certificate verification, use either the--verify-sslCLI option or theINSTANA_SSL_VERIFYenvironment variable.
The--verify-ssloption is equivalent to setting:
export INSTANA_SSL_VERIFY=true uv run src/core/server.py
SSL verification is disabled whenINSTANA_SSL_VERIFYis set to0,false, orno(case-insensitive), or left unset. Any other value enables verification — usetrue,1, oryesas the conventional choices.
When SSL verification is enabled, the system CA bundle is used by default. To use a custom CA certificate bundle, setINSTANA_CA_BUNDLE:
export INSTANA_SSL_VERIFY=true export INSTANA_CA_BUNDLE=/path/to/ca-bundle.crt uv run src/core/server.py
INSTANA_CA_BUNDLEis only used when SSL certificate verification is enabled.
The server logs the effective SSL verification state at startup, so you can immediately confirm whether your environment variable or CLI flag was picked up.
Once started, you can verify the server is running:
# 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.
SSL / Certificate Issues:See theSSL Certificate Verificationsection above for configuration options. If you encounter SSL errors with verification enabled and are using macOS, 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:
Bob is IBM's AI-powered IDE that natively supports MCP integration. Bob provides a seamless development experience with built-in AI assistance and observability tools.
The Streamable HTTP mode provides a REST API interface for MCP communication using JSON-RPC over HTTP.
Step 1: Start the MCP Server in Streamable HTTP Mode
Before configuring Bob, you need to start the MCP server in Streamable HTTP mode. Please refer to theStarting the Local MCP Serversection for detailed instructions.
On the top right corner of the Bob panel, you would see a dropdown with MCP servers:
On selecting this, you should be able to see the option to configure MCP at the project level or the global level.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
