# 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:

```py
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.*

## ContextForge Integration

### Registration with ContextForge

*TBD: Document registration with ContextForge.*

### 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`:

```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.*
