Instana Mcp Server

What is Instana Mcp Server about?

Instana Mcp Server enables seamless interaction between Model Context Protocol (MCP) clients (e.g., Claude Desktop, Bob IDE, Copilot) and the Instana observability APIs. It acts as a proxy that receives tool requests, performs the appropriate Instana API calls, and formats the responses for downstream LLM processing.

How to use Instana Mcp Server?

1. Installation – Install the package from PyPI:

   pip install mcp-instana
   

   or set up a development environment with uv.
2. Start the server – Choose a transport mode:
   • Streamable HTTP (recommended):

     mcp-instana --transport streamable-http
     

   • Stdio (for clients that communicate via stdin/stdout):

     mcp-instana --transport stdio
     

   Additional flags allow you to specify port, logging level, tool categories, and SSL verification.
3. Configure authentication – For streamable‑HTTP mode, supply Instana credentials via HTTP headers (instana-base-url, instana-api-token, etc.). In stdio mode, provide them via environment variables (INSTANA_BASE_URL, INSTANA_API_TOKEN).
4. Connect a client – Point your MCP client to the server URL (e.g., http://localhost:8080/mcp) and include the required headers or env vars.

Key features of Instana Mcp Server

• Dual transport modes – Streamable HTTP and Stdio for flexible client integration.
• Header‑based authentication – Supports API token, session token, and JWT flows without persisting secrets in the environment.
• Tool categorisation – Enable only needed tool groups (app, infra, events, etc.) to reduce startup time and memory usage.
• SSL verification control – Enabled by default; can be disabled or configured with a custom CA bundle.
• Catalog response caching – In‑process caching of metric/tag catalogs with configurable TTL and per‑request overrides.
• Docker ready – Official Dockerfile for production deployments.
• Extensive CLI options – Debug mode, custom log levels, port selection, and environment variable injection.

Use cases of Instana Mcp Server

• AI‑assisted troubleshooting – LLMs can fetch latest alerts, metrics, or configuration details directly from Instana during a chat session.
• Automated monitoring dashboards – Generate or modify custom dashboards programmatically via MCP tools.
• Incident response playbooks – Trigger remediation actions (e.g., create maintenance windows) from an AI‑driven workflow.
• Continuous delivery pipelines – Retrieve release information or SLO reports as part of CI/CD checks.
• Multi‑tenant environments – Run separate server instances or use header‑based credentials to query multiple Instana tenants from a single client.

FAQ from the Instana Mcp Server

Q: Do I need to set SSL verification for internal Instana instances with self‑signed certificates? A: Yes. Disable verification with --verify-ssl false or set INSTANA_SSL_VERIFY=false, or supply a custom CA bundle via INSTANA_CA_BUNDLE.

Q: Which transport mode should I choose? A: Streamable HTTP is recommended for most integrations because it allows per‑request header authentication and works well with shared environments. Stdio is useful when the client only supports stdin/stdout communication.

Q: How can I limit the tools that are loaded? A: Use the --tools flag with a comma‑separated list of categories (e.g., --tools app,infra). Run mcp-instana --list-tools to see all available categories.

Q: Is there support for caching to improve performance? A: Yes. Catalog responses are cached for 30 minutes by default. Control it with INSTANA_CACHE_ENABLED and INSTANA_CACHE_TTL, or override per request via instana-cache-enabled and instana-cache-ttl headers.

Q: How do I run the server in Docker? A: Build the image with docker build -t mcp-instana . and run docker run -p 8080:8080 mcp-instana. The container starts in streamable‑HTTP mode by default.

🔒 SSL Enabled by Default: Starting with this release 1.0.3, SSL certificate verification is enabled by default for all outgoing Instana API calls. You can customize this behaviour (disable, supply a custom CA bundle, etc.) via CLI flag, environment variable, or config.yaml. See SSL Certificate Verification for full details.

Table of Contents

• MCP Server for IBM Instana
  • Quick Links
  • Architecture Overview
  • Workflow
  • Prerequisites
  • Installing Instana MCP server
    • Option 1: Install from PyPI (Recommended)
    • Option 2: Development Installation
      • Installing uv
      • Setting Up the Environment
    • Header-Based Authentication for Streamable HTTP Mode
      • 1. API Token Authentication (Direct API Calls)
      • 2. Session Token Authentication (UI-Initiated Calls)
      • 3. JWT Token Authentication (IBM Platform Integration)
  • Starting the Local MCP Server
    • Server Command Options
      • Using the CLI (PyPI Installation)
      • Using Development Installation
    • Starting in Streamable HTTP Mode
      • Using CLI (PyPI Installation)
      • Using Development Installation
    • Starting in Stdio Mode
      • Using CLI (PyPI Installation)
      • Using Development Installation
    • Tool Categories
      • Using CLI (PyPI Installation)
      • Using Development Installation
    • SSL Certificate Verification
      • Using the CLI option
      • Using the environment variable
      • Using a custom CA bundle
    • Catalog Response Caching
      • Cached catalog operations
      • Configuring caching (stdio mode)
      • Configuring caching (streamable-http mode)
      • Using .bob/mcp.json (stdio mode)
    • Verifying Server Status
    • Common Startup Issues
  • Setup and Usage
    • Supported MCP Clients
    • Connecting to Multiple Instana MCP Servers
  • Available Tools
  • Tool Filtering
    • Usage Examples
      • Using CLI (PyPI Installation)
      • Using Development Installation
    • Benefits of Tool Filtering
  • Docker Deployment
    • Building the Docker Image
      • Prerequisites
      • Build and Run
  • General Issues

MCP Server for IBM Instana

Quick Links

• 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 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

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

Prerequisites

• python - version 3.10 or higher
• pip - version 21.3 or higher (only required for pypi based installation)
• uv - version 0.11.6 or higher (only required for development installation)

Installing Instana MCP server

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
• Supporting both API token and session-based authentication

Supported Authentication Modes:

1. API Token Authentication (Direct API Calls)

Required Headers:

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

Example:

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-api-token: your-api-token"

2. Session Token Authentication (UI-Initiated Calls)

Required Headers:

• instana-base-url: Your Instana instance URL
• instana-auth-token: Session authentication token from UI backend
• instana-csrf-token: CSRF token from UI backend
• instana-cookie-name: (Optional) Cookie name for session auth (default: instanaAuthToken)

Example:

--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 Token Authentication (IBM Platform Integration)

Required Headers:

• instana-base-url: Your Instana instance URL
• instana-jwt-token: JWT token from IBM Platform
• instana-csrf-token: CSRF token for request validation

Example Configuration:

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

Authentication Priority:

1. JWT Token (if provided with CSRF token) - Takes precedence for IBM Platform integration
2. Session Tokens (if both auth_token and csrf_token provided)
3. API Token (if provided) - Standard authentication
4. Environment Variable (INSTANA_API_TOKEN) - Fallback

Authentication Flow:

1. HTTP headers must be present in each request
2. Server validates credentials based on priority order
3. 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. Check here for more information.

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)
• --verify-ssl [BOOL]: Enable or disable SSL certificate verification for outgoing Instana API calls (default: true). Pass false/0/noto disable. Equivalent to settingINSTANA_SSL_VERIFY=false`.
• --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: Pass the base url and api token directly 
mcp-instana --base-url https://your-instana-instance.instana.io --api-token your_instana_api_token

# Or with explicit stdio mode
mcp-instana --transport stdio --base-url https://your-instana-instance.instana.io --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: Pass the base url and api token directly 
uv run src/core/server.py --base-url https://your-instana-instance.instana.io --api-token your_instana_api_token

# Or with explicit stdio mode
uv run src/core/server.py --transport stdio --base-url https://your-instana-instance.instana.io --api-token your_instana_api_token

Key Features of Stdio Mode:

• Uses environment variables for authentication (can be set via export or --env flags)
• Direct communication via stdin/stdout
• Required for certain MCP client configurations
• The --api-token and base-url flags 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

SSL Certificate Verification

SSL certificate verification for outgoing Instana API calls is enabled by default. This applies to both Streamable HTTP and Stdio transport modes.

To disable SSL certificate verification (e.g. for environments with self-signed or internal certificates), use the --verify-ssl CLI option, the INSTANA_SSL_VERIFY environment variable, or the sslVerify key in config.yaml.

Using the CLI option

# Disable SSL verification
uv run src/core/server.py --verify-ssl false

# Explicitly enable (default behaviour, no flag needed)
uv run src/core/server.py --verify-ssl true

Using the environment variable

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

SSL verification is disabled when INSTANA_SSL_VERIFY is set to 0, false, or no (case-insensitive). Any other value, or when the variable is unset, keeps verification enabled.

Using config.yaml (SaaS / Kubernetes deployments)

# SSL verification for outbound API calls (default: true)
sslVerify: false

The sslVerify key is read by start.sh at startup and exported as INSTANA_SSL_VERIFY.

Using a custom CA bundle

When SSL verification is enabled, the system CA bundle is used by default. To use a custom CA certificate bundle, set 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 is 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, CLI flag, or config file setting was picked up.

API Call Timeout

Every outgoing Instana API call is subject to a hard wall-clock timeout. If the Instana server does not respond within the deadline the call is cancelled and an error is returned immediately — no indefinitely hanging requests.

The default timeout is 180 seconds. Override it with the INSTANA_API_TIMEOUT environment variable:

export INSTANA_API_TIMEOUT=60   # 60-second deadline
uv run src/core/server.py

INSTANA_API_TIMEOUT must be a positive integer (seconds). Non-integer or non-positive values are ignored and the 180-second default is used instead.

Catalog Response Caching

The server caches catalog API responses (metrics, tags, and plugins) in-process to eliminate redundant round-trips. Catalog data is stable within a tenant — it only changes when new integrations are deployed — so responses are safe to reuse across the lifetime of a single server process.

Default TTL: 30 minutes. Each unique combination of tenant URL, method, and parameters gets its own independent cache slot. Error responses are never cached, so a transient network failure cannot poison the store.

Cached catalog operations

Configuring caching (stdio mode)

Set environment variables before starting the server. In stdio mode these are the only values used — no restart is required when using Bob, as the server reboots automatically.

# Disable caching entirely
export INSTANA_CACHE_ENABLED=false
# Override TTL to 5 minutes (default: 1800)
export INSTANA_CACHE_TTL=300

INSTANA_CACHE_ENABLED is treated as disabled when set to false, 0, or no (case-insensitive). Any other value keeps caching enabled.

Configuring caching (streamable-http mode)

In addition to the environment variables above, every HTTP request can override the cache settings via headers. Per-request headers take precedence over the process-level defaults, so caching can be toggled on or off without restarting the server.

instana-cache-enabled: false
instana-cache-ttl: 300

To set cache headers persistently in your MCP client config (e.g. .bob/mcp.json for streamable-http mode), add them alongside the existing Instana headers:

{
  "mcpServers": {
    "Instana MCP Server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "instana-cache-enabled": "true",
        "instana-cache-ttl": "1800"
      }
    }
  }
}

To disable caching for a specific client connection:

{
  "mcpServers": {
    "Instana MCP Server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "instana-cache-enabled": "false"
      }
    }
  }
}

Using .bob/mcp.json (stdio mode)

To set cache configuration persistently for Bob, add the env vars to the env block in .bob/mcp.json:

{
  "mcpServers": {
    "instana": {
      "env": {
        "INSTANA_CACHE_ENABLED": "true",
        "INSTANA_CACHE_TTL": "1800"
      }
    }
  }
}

The server logs the effective cache state at DEBUG level on every catalog call, showing whether a response was a cache HIT or MISS.

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

SSL / Certificate Issues: See the SSL Certificate Verification section 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:

uv sync

Setup and Usage

Supported MCP Clients

Connecting to Multiple Instana MCP Servers

You can configure your MCP client to connect to multiple instances. Below is a sample configuration:

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

To target a specific server, ensure that:

• The server is configured with the appropriate environment name in the MCP configuration (e.g. Instana MCP Server1)
• The prompt explicitly mentions the server/environment name.

The request will then be routed to the corresponding configured server. If no server/environment is explicitly mentioned in the prompt, MCP uses the first server defined in the configuration as the default server.

Note: If the requested server is down or unreachable, MCP behaves as expected and forwards the API failure. The user will receive the corresponding error returned by the API, indicating that the server is unavailable. MCP relies on the underlying API availability and does not perform automatic failover.

Available Tools

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.

Usage Examples

Using CLI (PyPI Installation)

# Enable only application monitoring tools
mcp-instana --tools app --transport streamable-http

# Enable only infrastructure analysis tools
mcp-instana --tools infra --transport streamable-http

# Enable application and infrastructure tools
mcp-instana --tools app,infra --transport streamable-http

# Enable events and website tools
mcp-instana --tools events,website --transport streamable-http

# Enable settings (custom dashboards) and app tools
mcp-instana --tools settings,app --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,events --transport streamable-http

# Enable automation and app tools
mcp-instana --tools automation,app --transport streamable-http

# Enable SLO management tools
mcp-instana --tools slo --transport streamable-http

# Enable synthetic monitoring tools
mcp-instana --tools synthetic --transport streamable-http

# Enable mobile app monitoring tools
mcp-instana --tools mobile_app --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 application monitoring tools
uv run src/core/server.py --tools app --transport streamable-http

# Enable only infrastructure analysis tools
uv run src/core/server.py --tools infra --transport streamable-http

# Enable application and infrastructure tools
uv run src/core/server.py --tools app,infra --transport streamable-http

# Enable events and website tools
uv run src/core/server.py --tools events,website --transport streamable-http

# Enable settings (custom dashboards) and app tools
uv run src/core/server.py --tools settings,app --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,events --transport streamable-http

# Enable automation and app tools
uv run src/core/server.py --tools automation,app --transport streamable-http

# Enable SLO management tools
uv run src/core/server.py --tools slo --transport streamable-http

# Enable synthetic monitoring tools
uv run src/core/server.py --tools synthetic --transport streamable-http

# Enable mobile app monitoring tools
uv run src/core/server.py --tools mobile_app --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

Docker Deployment

The MCP Instana server can be deployed using Docker for production environments. The Docker setup is optimized for security, performance, and minimal resource usage.

Building the Docker Image

Prerequisites

• Docker installed and running
• Access to the project source code

Build and Run

# Ensure you are in the mcp-instana directory of your repo
# Build the optimized production image
docker build -t mcp-instana:latest .

The above command would build the image using the instructions in the Dockerfile. The default port is 8080 and transport mode is streamable-http

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

If you want to use a custom port on your host (ex: 9000)

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

Connecting to mcp-instana container in streamable mode

Assuming your started your container using the command: docker run -p 8080:8080 mcp-instana

Your MCP Client would connect to the Host port (8080). By default, the container runs in streamable mode.

Here is a sample configuration for your MCP client:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http",
        "--header",
        "instana-base-url: https://your-instana-instance.instana.io",
        "--header",
            "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Connecting to mcp-instana in stdio mode

In stdio mode, you can have your MCP Client to start and connect to the container. Here you are explicitly specifying to run in stdio by providing a value for the --transport flag.

Below is a sample configuration:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "INSTANA_API_TOKEN=your_instana_api_token",
        "-e", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "mcp-instana",
        "--transport", "stdio"
      ]
    }
  }
}

For more details, check the Docker deployment guide here

For comprehensive Docker documentation including multi-architecture builds, .dockerignore, security best practices, and production deployment examples, see DOCKER.md.

General Issues

• GitHub Copilot

  • If you encounter issues with GitHub Copilot, try starting/stopping/restarting the server in the mcp.json file and keep only one server running at a time.

• Certificate Issues

  • If you encounter certificate issues, such as [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
    • Check that you can reach the Instana API endpoint using curl or wget with SSL verification.
      • If that works, your Python environment may not be able to verify the certificate and might not have access to the same certificates as your shell or system. Ensure your Python environment uses system certificates (macOS). You can do this by installing certificates to Python: /Applications/Python\ 3.13/Install\ Certificates.command
    • If you cannot reach the endpoint with SSL verification, try without it. If that works, check your system's CA certificates and ensure they are up-to-date.