IBM Instana MCP Server

offiziell

Der IBM Instana MCP Server ermöglicht eine nahtlose Interaktion mit der IBM Instana Observability-Plattform und erlaubt den direkten Zugriff auf Echtzeit-Observability-Daten innerhalb Ihres Entwicklungsworkflows.

GitHub

Was kann man mit IBM Instana MCP machen?

Instana-Alarme abfragen — Fordern Sie die neuesten Alarme von Instana für eine bestimmte Anwendung an und erhalten Sie eine Zusammenfassung in natürlicher Sprache.
Anwendungen und Infrastruktur verwalten — Rufen Sie Anwendungsmetriken, Alarmkonfigurationen, Einstellungen und Infrastruktur-Snapshots über die Tools des Servers ab.
SLOs und Releases verfolgen — Listen Sie SLO-Konfigurationen und -Berichte auf oder durchsuchen und verwalten Sie Release-Datensätze mit Zeitzonenbehandlung.
Wartungsfenster verwalten — Erstellen, ändern, schließen und listen Sie Wartungsfenster auf, einschließlich Unterstützung für Vorlagen und ServiceNow-Integration.
Websites und mobile Apps überwachen — Analysieren Sie Leistungsmetriken von Websites und mobilen Apps, Beacons und Session-Replay-Daten.
Aktivierte Tool-Kategorien filtern — Starten Sie den Server mit nur den benötigten Tool-Kategorien mithilfe der Option --tools.

Dokumentation

🔒 SSL standardmäßig aktiviert: Ab dieser Version 1.0.3 ist die SSL-Zertifikatsprüfung für alle ausgehenden Instana-API-Aufrufe standardmäßig aktiviert. Sie können dieses Verhalten (deaktivieren, ein benutzerdefiniertes CA-Bundle bereitstellen usw.) über ein CLI-Flag, eine Umgebungsvariable oder config.yaml anpassen. Vollständige Details finden Sie unter SSL-Zertifikatsprüfung.

Inhaltsverzeichnis

MCP-Server für IBM Instana

MCP-Server für IBM Instana

Schnellzugriff

Tools & Beispiele - Umfassende Tool-Dokumentation mit praxisnahen Beispielen
Datenschutzrichtlinie - Informationen zur Datenverarbeitung und zum Datenschutz
Docker-Bereitstellungshandbuch - Umfassende Docker-Bereitstellung, Multi-Architektur-Builds und Produktionseinrichtung

Der Instana MCP-Server ermöglicht eine nahtlose Interaktion mit der Instana-Observability-Plattform und erlaubt Ihnen den direkten Zugriff auf Echtzeit-Observability-Daten innerhalb Ihres Entwicklungsworkflows.

Er dient als Brücke zwischen Clients (wie KI-Agenten oder benutzerdefinierten Tools) und den Instana-REST-APIs, indem er Benutzeranfragen in Instana-API-Anfragen umwandelt und die Antworten in strukturierte, leicht nutzbare Formate bringt.

Der Server unterstützt sowohl Streamable HTTP als auch Stdio als Transportmodi für maximale Kompatibilität mit verschiedenen MCP-Clients. Weitere Details finden Sie in der MCP Transport Modes specification.

Architekturübersicht

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

Betrachten Sie ein einfaches Beispiel: Sie verwenden einen MCP-Host (wie Claude Desktop, VS Code oder einen anderen Client), der mit dem Instana MCP-Server verbunden ist. Wenn Sie Informationen zu Instana-Alarmen anfordern, läuft der folgende Prozess ab:

Der MCP-Client ruft die Liste der verfügbaren Tools vom Instana MCP-Server ab
Ihre Anfrage wird zusammen mit den Tool-Beschreibungen an das LLM gesendet
Das LLM analysiert die verfügbaren Tools und wählt das bzw. die geeigneten für den Abruf von Instana-Alarmen aus
Der Client führt das bzw. die ausgewählten Tools über den Instana MCP-Server aus
Die Ergebnisse (neueste Alarme) werden an das LLM zurückgegeben
Das LLM formuliert eine Antwort in natürlicher Sprache
Die Antwort wird Ihnen angezeigt

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

Voraussetzungen

python - Version 3.10 oder höher
pip - Version 21.3 oder höher (nur erforderlich für die PyPI-basierte Installation)
uv - Version 0.11.6 oder höher (nur erforderlich für die Entwicklungsinstallation)

Instana MCP-Server installieren

Option 1: Installation von PyPI (empfohlen)

Der einfachste Weg, mcp-instana zu verwenden, ist die direkte Installation von PyPI:

pip install mcp-instana

Nach der Installation können Sie den Server direkt mit dem Befehl mcp-instana ausführen.

Option 2: Entwicklungsinstallation

Für Entwicklung oder lokale Anpassungen können Sie das Projekt lokal klonen und einrichten.

uv installieren

Dieses Projekt verwendet uv, einen schnellen Python-Paketinstaller und -Resolver. Zur Installation von uv haben Sie mehrere Möglichkeiten:

Mit pip:

pip install uv

Mit Homebrew (macOS):

brew install uv

Weitere Installationsoptionen und detaillierte Anweisungen finden Sie in der uv-Dokumentation.

Umgebung einrichten

Nach der Installation von uv richten Sie die Projektumgebung ein, indem Sie Folgendes ausführen:

uv sync

Header-basierte Authentifizierung für den Streamable-HTTP-Modus

Bei Verwendung des Streamable-HTTP-Modus müssen Sie Instana-Anmeldedaten über HTTP-Header übergeben. Dieser Ansatz erhöht Sicherheit und Flexibilität durch:

Vermeidung der Speicherung von Anmeldedaten in Umgebungsvariablen
Ermöglichung der Verwendung unterschiedlicher Anmeldedaten für unterschiedliche Anfragen
Unterstützung gemeinsam genutzter Umgebungen, in denen das Ändern von Umgebungsvariablen eingeschränkt ist
Unterstützung sowohl der API-Token- als auch der sitzungsbasierten Authentifizierung

Unterstützte Authentifizierungsmodi:

1. API-Token-Authentifizierung (direkte API-Aufrufe)

Erforderliche Header:

instana-base-url: Ihre Instana-Instanz-URL
instana-api-token: Ihr Instana-API-Token

Beispiel:

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

2. Sitzungstoken-Authentifizierung (UI-initiierte Aufrufe)

Erforderliche Header:

instana-base-url: Ihre Instana-Instanz-URL
instana-auth-token: Sitzungsauthentifizierungstoken vom UI-Backend
instana-csrf-token: CSRF-Token vom UI-Backend
instana-cookie-name: (Optional) Cookie-Name für die Sitzungsauthentifizierung (Standard: instanaAuthToken)

Beispiel:

--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-Authentifizierung (IBM-Plattform-Integration)

Erforderliche Header:

instana-base-url: Ihre Instana-Instanz-URL
instana-jwt-token: JWT-Token von der IBM-Plattform
instana-csrf-token: CSRF-Token zur Anfragevalidierung

Beispielkonfiguration:

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

Authentifizierungspriorität:

JWT-Token (falls mit CSRF-Token bereitgestellt) - Hat Vorrang für die IBM-Plattform-Integration
Sitzungstoken (falls sowohl auth_token als auch csrf_token bereitgestellt werden)
API-Token (falls bereitgestellt) - Standardauthentifizierung
Umgebungsvariable (INSTANA_API_TOKEN) - Fallback

Authentifizierungsablauf:

HTTP-Header müssen in jeder Anfrage vorhanden sein
Der Server validiert die Anmeldedaten gemäß der Prioritätsreihenfolge
Anfragen ohne gültige Authentifizierung schlagen fehl

Dieses Design gewährleistet eine sichere Übertragung von Anmeldedaten und unterstützt mehrere Authentifizierungsabläufe, einschließlich UI-initiierter Aufrufe über WebSocket → Coordinator → MCP Server.

Stellen Sie sicher, dass das verwendete Token über die erforderlichen Berechtigungen zum Aufrufen von MCP-Tools verfügt. Weitere Informationen finden Sie hier.

Lokalen MCP-Server starten

Bevor Sie einen MCP-Client (Claude Desktop, GitHub Copilot oder benutzerdefinierte MCP-Clients) konfigurieren, müssen Sie den lokalen MCP-Server starten. Der Server unterstützt zwei Transportmodi: Streamable HTTP und Stdio.

Server-Befehlsoptionen

Verwendung der CLI (PyPI-Installation)

Wenn Sie mcp-instana von PyPI installiert haben, verwenden Sie den Befehl mcp-instana:

mcp-instana [OPTIONS]

Verwendung der Entwicklungsinstallation

Für die lokale Entwicklung verwenden Sie den Befehl uv run:

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

Verfügbare Optionen:

--transport <mode>: Transportmodus (Auswahl: streamable-http, stdio)
--debug: Debug-Modus mit zusätzlicher Protokollierung aktivieren
--log-level <level>: Protokollierungsstufe festlegen (Auswahl: DEBUG, INFO, WARNING, ERROR, CRITICAL)
--tools <categories>: Kommagetrennte Liste der zu aktivierenden Tool-Kategorien (z. B. infra,app,events,website). Das Aktivieren einer Kategorie aktiviert auch die zugehörigen Prompts. Zum Beispiel: --tools infra aktiviert die Infra-Tools und alle Infra-bezogenen Prompts.
--list-tools: Alle verfügbaren Tool-Kategorien auflisten und beenden
--port <port>: MCP-Server-Port (Standard: 8080, kann mit der Umgebungsvariable PORT überschrieben werden)
--admin-port <port>: Admin-Server-Port für Health Checks (Standard: 8601, kann mit der Umgebungsvariable ADMIN_PORT überschrieben werden)
--verify-ssl [BOOL]: SSL-Zertifikatsprüfung für ausgehende Instana-API-Aufrufe aktivieren oder deaktivieren (Standard: true). Übergeben Sie false/0/no zum Deaktivieren. Entspricht dem Setzen von INSTANA_SSL_VERIFY=false.
--stream-read-buffer-size <SIZE>: Bytes pro I/O-Leseaufruf, die von Streaming-Parsern verwendet werden (Standard: 65536 / 64k). Akzeptiert eine reine Byte-Anzahl oder ein benutzerfreundliches Suffix: 64k, 64kb, 64m, 64mb, 64g, 64gb. Kann auch über die Umgebungsvariable STREAM_READ_BUFFER_SIZE festgelegt werden.
--help: Hilfemeldung anzeigen und beenden

Im Streamable-HTTP-Modus starten

Der Streamable-HTTP-Modus bietet eine REST-API-Schnittstelle und wird für die meisten Anwendungsfälle empfohlen.

Verwendung der 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

Verwendung der Entwicklungsinstallation

# 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

Hauptmerkmale des Streamable-HTTP-Modus:

Verwendet HTTP-Header zur Authentifizierung (keine Umgebungsvariablen erforderlich)
Unterstützt unterschiedliche Anmeldedaten pro Anfrage
Besser geeignet für gemeinsam genutzte Umgebungen
Standardport des MCP-Servers: 8080
MCP-Endpunkt: http://0.0.0.0:8080/mcp/

Im Stdio-Modus starten

Der Stdio-Modus verwendet die Standardeingabe/-ausgabe zur Kommunikation und erfordert Umgebungsvariablen zur Authentifizierung.

Verwendung der CLI (PyPI-Installation)

# 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

Verwendung der Entwicklungsinstallation

# 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

Hauptmerkmale des Stdio-Modus:

Verwendet Umgebungsvariablen zur Authentifizierung (kann über export oder die Datei .env festgelegt werden)
Direkte Kommunikation über stdin/stdout
Erforderlich für bestimmte MCP-Client-Konfigurationen

Tool-Kategorien

Sie können die Serverleistung optimieren, indem Sie nur die benötigten Tool- und Prompt-Kategorien aktivieren:

Verwendung der 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

Verwendung der Entwicklungsinstallation

# 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-Zertifikatsprüfung

Die SSL-Zertifikatsprüfung für ausgehende Instana-API-Aufrufe ist standardmäßig aktiviert. Dies gilt sowohl für den Streamable-HTTP- als auch den **Stdio-**Transportmodus.

Um die SSL-Zertifikatsprüfung zu deaktivieren (z. B. für Umgebungen mit selbstsignierten oder internen Zertifikaten), verwenden Sie die CLI-Option --verify-ssl, die Umgebungsvariable INSTANA_SSL_VERIFY oder den Schlüssel sslVerify in config.yaml.

Verwendung der 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

Verwendung der Umgebungsvariable

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

Die SSL-Verifizierung ist deaktiviert, wenn INSTANA_SSL_VERIFY auf 0, false oder no gesetzt ist (Groß-/Kleinschreibung wird nicht unterschieden). Jeder andere Wert oder eine nicht gesetzte Variable lässt die Verifizierung aktiviert.

Verwendung von config.yaml (SaaS-/Kubernetes-Deployments)

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

Der Schlüssel sslVerify wird beim Start von start.sh gelesen und als INSTANA_SSL_VERIFY exportiert.

Verwendung eines benutzerdefinierten CA-Bundles

Wenn die SSL-Verifizierung aktiviert ist, wird standardmäßig das System-CA-Bundle verwendet. Um ein benutzerdefiniertes CA-Zertifikatsbundle zu verwenden, setzen Sie 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 wird nur verwendet, wenn die SSL-Zertifikatsverifizierung aktiviert ist.

Der Server protokolliert beim Start den effektiven SSL-Verifizierungsstatus, sodass Sie sofort bestätigen können, ob Ihre Umgebungsvariable, Ihr CLI-Flag oder Ihre Konfigurationsdateieinstellung übernommen wurde.

API-Aufruf-Timeout

Jeder ausgehende Instana-API-Aufruf unterliegt einem harten Wall-Clock-Timeout. Wenn der Instana-Server nicht innerhalb der Frist antwortet, wird der Aufruf abgebrochen und sofort ein Fehler zurückgegeben — keine unbegrenzt hängenden Anfragen.

Das Standard-Timeout beträgt 180 Sekunden. Überschreiben Sie es mit der Umgebungsvariable INSTANA_API_TIMEOUT:

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

INSTANA_API_TIMEOUT muss eine positive Ganzzahl (Sekunden) sein. Nicht-ganzzahlige oder nicht-positive Werte werden ignoriert und stattdessen wird der Standardwert von 180 Sekunden verwendet.

Catalog-Antwort-Caching

Der Server cached Catalog-API-Antworten (Metriken, Tags und Plugins) prozessintern, um redundante Round-Trips zu vermeiden. Catalog-Daten sind innerhalb eines Tenants stabil — sie ändern sich nur, wenn neue Integrationen bereitgestellt werden — daher können Antworten während der Lebensdauer eines einzelnen Serverprozesses sicher wiederverwendet werden.

Standard-TTL: 30 Minuten. Jede eindeutige Kombination aus Tenant-URL, Methode und Parametern erhält ihren eigenen unabhängigen Cache-Slot. Fehlerantworten werden niemals gecached, sodass ein vorübergehender Netzwerkfehler den Speicher nicht vergiften kann.

Gecachte Catalog-Operationen

Domäne	Operation	Cache-Schlüssel-Diskriminatoren
Application	Metrik-Catalog abrufen	—
Application	Tag-Catalog abrufen	`use_case`, `data_source`
Website	Metrik-Catalog abrufen	—
Website	Tag-Catalog abrufen	`beacon_type`, `use_case`
Mobile App	Metrik-Catalog abrufen	—
Mobile App	Tag-Catalog abrufen	`beacon_type`, `use_case`
Synthetic	Metrik-Catalog abrufen	—
Synthetic	Tag-Catalog abrufen	`use_case`
Infrastructure	Metrik-Catalog abrufen	`plugin`, `filter`
Infrastructure	Tag-Catalog abrufen	`plugin`

Caching konfigurieren (stdio-Modus)

Setzen Sie Umgebungsvariablen, bevor Sie den Server starten. Im stdio-Modus werden nur diese Werte verwendet — bei Verwendung von Bob ist kein Neustart erforderlich, da der Server automatisch neu startet.

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

INSTANA_CACHE_ENABLED gilt als deaktiviert, wenn es auf false, 0 oder no gesetzt ist (Groß-/Kleinschreibung wird nicht unterschieden). Jeder andere Wert lässt das Caching aktiviert.

Caching konfigurieren (streamable-http-Modus)

Zusätzlich zu den oben genannten Umgebungsvariablen kann jede HTTP-Anfrage die Cache-Einstellungen über Header überschreiben. Header pro Anfrage haben Vorrang vor den prozessweiten Standardwerten, sodass das Caching ohne Neustart des Servers ein- oder ausgeschaltet werden kann.

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

Um Cache-Header dauerhaft in Ihrer MCP-Client-Konfiguration festzulegen (z. B. .bob/mcp.json für den streamable-http-Modus), fügen Sie sie neben den vorhandenen Instana-Headern hinzu:

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

Um das Caching für eine bestimmte Client-Verbindung zu deaktivieren:

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

Verwendung von .bob/mcp.json (stdio-Modus)

Um die Cache-Konfiguration dauerhaft für Bob festzulegen, fügen Sie die Umgebungsvariablen dem Block env in .bob/mcp.json hinzu:

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

Der Server protokolliert den effektiven Cache-Status bei jedem Catalog-Aufruf auf DEBUG-Ebene und zeigt an, ob eine Antwort ein Cache-HIT oder -MISS war.

Überprüfen des Serverstatus

Nach dem Start können Sie überprüfen, ob der Server läuft:

Für den Streamable-HTTP-Modus:

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

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

Für den Stdio-Modus: Der Server startet und wartet auf stdin-Eingaben von MCP-Clients.

Häufige Startprobleme

SSL-/Zertifikatsprobleme: Siehe den Abschnitt SSL-Zertifikatsverifizierung oben für Konfigurationsoptionen. Wenn bei aktivierter Verifizierung SSL-Fehler auftreten und Sie macOS verwenden, stellen Sie sicher, dass Ihre Python-Umgebung Zugriff auf die Systemzertifikate hat:

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

Port bereits in Verwendung: Wenn Port 8080 bereits in Verwendung ist, geben Sie einen anderen Port an:

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

Fehlende Abhängigkeiten: Stellen Sie sicher, dass alle Abhängigkeiten installiert sind:

uv sync

Einrichtung und Verwendung

Unterstützte MCP-Clients

Client	Transporte
Bob IDE	`streamable http`, `stdio`
Bob CLI	`streamable http`, `stdio`
Claude Desktop	`streamable http`, `stdio`
Cursor IDE	`streamable http`, `stdio`
Kiro IDE	`streamable http`, `stdio`
Kiro CLI	`streamable http`, `stdio`
Github Copilot	`streamable http`, `stdio`
Copilot CLI	`streamable http`, `stdio`
Mistral AI	`streamable http`
Gemini Cli	`streamable http`, `stdio`

Verbindung mit mehreren Instana MCP Servern

Sie können Ihren MCP-Client so konfigurieren, dass er eine Verbindung zu mehreren Instanzen herstellt. Nachfolgend finden Sie eine Beispielkonfiguration:

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

Um einen bestimmten Server anzusprechen, stellen Sie sicher, dass:

Der Server in der MCP-Konfiguration mit dem entsprechenden Umgebungsnamen konfiguriert ist (z. B. Instana MCP Server1)
Der Prompt den Server-/Umgebungsnamen explizit erwähnt.

Die Anfrage wird dann an den entsprechend konfigurierten Server weitergeleitet. Wenn im Prompt kein Server/keine Umgebung explizit erwähnt wird, verwendet MCP den ersten in der Konfiguration definierten Server als Standardserver.

Hinweis: Wenn der angeforderte Server ausgefallen oder nicht erreichbar ist, verhält sich MCP wie erwartet und leitet den API-Fehler weiter. Der Benutzer erhält den entsprechenden von der API zurückgegebenen Fehler, der anzeigt, dass der Server nicht verfügbar ist. MCP verlässt sich auf die Verfügbarkeit der zugrunde liegenden API und führt kein automatisches Failover durch.

Verfügbare Tools

Tool	Kategorie	Beschreibung
`manage_applications`	Application & Infrastructure	Einheitliches Tool zur Verwaltung von Anwendungsmetriken, Alert-Konfigurationen, Einstellungen und Catalog
`manage_websites`	Website Monitoring	Einheitlicher Smart Router für Website-Analyse, Catalog, Konfiguration und erweiterte Konfigurationsoperationen
`manage_custom_dashboards`	Custom Dashboards	Einheitliches Tool zur Verwaltung von CRUD-Operationen für benutzerdefinierte Dashboards
`manage_infrastructure`	Infrastructure	Einheitlicher Smart Router für Infrastruktur-Analyse, Catalog (`get_plugin_schema`), Smart-Alert-Konfigurationen und Snapshot-Ressourcenoperationen
`manage_automation`	Automation	Einheitlicher Smart Router für Automatisierung: Action-Catalog durchsuchen und Ausführungsverlauf anzeigen
`manage_events`	Events	Einheitlicher Smart Router für Event-Monitoring: Event nach ID abrufen, Events nach IDs abrufen, Kubernetes-Events, Agent-Monitoring-Events und alle Events
`manage_slo`	SLO Management	Einheitlicher Smart Router für SLO-Konfigurationen, Berichte, Alerts und Korrekturfenster mit intelligenter Zeitzonenbehandlung
`manage_releases`	Release Management	Einheitlicher Smart Router für Release-Tracking: Releases mit Paginierung und Namensfilterung auflisten, Release-Details abrufen, Releases mit Zeitzonenunterstützung erstellen/aktualisieren/löschen
`manage_maintenance_windows`	Maintenance Windows	Einheitlicher Smart Router für die Lebenszyklusverwaltung von Wartungsfenstern: Wartungsfenster mit Vorlagenunterstützung und ServiceNow-Integration erstellen, ändern, schließen und auflisten
`manage_mobile_apps`	Mobile App Monitoring	Einheitlicher Smart Router für Mobile-App-Monitoring: Beacons, Performance-Metriken, Session Replay, Konfiguration und Alert-Verwaltung analysieren
`manage_synthetics`	Synthetic Monitoring	Einheitlicher Smart Router für Synthetic Monitoring: Catalog, Metriken, Einstellungen (schreibgeschützt) und Test-Playback-Ergebnisse

Für detaillierte Tool-Dokumentation, Funktionen und technische Referenz siehe Tools & Examples

Tool-Filterung

Der MCP-Server unterstützt das selektive Laden von Tools, um die Leistung zu optimieren und den Ressourcenverbrauch zu reduzieren. Sie können nur die Tool-Kategorien aktivieren, die Sie für Ihren spezifischen Anwendungsfall benötigen.

Verwendungsbeispiele

Verwendung der 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

Verwendung der Entwicklungsinstallation

# 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 custom_dashboards and application tools
uv run src/core/server.py --tools custom_dashboards,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

# Disable specific categories (all others remain enabled)
uv run src/core/server.py --transport streamable-http --omit-tools maintenance_windows,slo

# Combine --tools and --omit-tools
uv run src/core/server.py --transport streamable-http --tools app,infra,events --omit-tools events


# List all available tool categories and their tools
uv run src/core/server.py --list-tools

Tool-Filterung im Stdio-Modus

Im stdio-Modus startet der MCP-Client den Server als Kindprozess, sodass Flags direkt über das Array args in mcp.json übergeben werden.

Verwendung von --tools (Allowlist) — nur die aufgelisteten Kategorien anzeigen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio", "--tools", "infra,events"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Verwendung von --omit-tools (Denylist) — alles außer den aufgelisteten Kategorien anzeigen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio", "--omit-tools", "maintenance_windows,slo"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Beides kombinieren — eine Teilmenge auswählen und dann daraus entfernen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio", "--tools", "app,infra,events", "--omit-tools", "events"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Tool-Filterung über HTTP-Header (Streamable-HTTP-Modus)

Wenn der Server im streamable HTTP-Modus läuft, kann jeder MCP-Client steuern, welche Tool-Kategorien er sieht, ohne den Server neu zu starten oder eine separate Instanz auszuführen. Zwei komplementäre Header werden unterstützt:

Header	Verhalten
`select-tools`	Allowlist — nur die aufgelisteten Kategorien anzeigen
`omit-tools`	Denylist — alles außer den aufgelisteten Kategorien anzeigen

Beide Header akzeptieren eine kommagetrennte Liste von Kategorienamen, die identisch mit denen der CLI-Flags --tools / --omit-tools sind. Sie können kombiniert werden: select-tools wird zuerst angewendet, um die sichtbare Menge zu erstellen, dann entfernt omit-tools daraus.

Verwendung von `select-tools` (Allowlist)

Nur die angegebenen Kategorien anzeigen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "select-tools": "infra,events"
      }
    }
  }
}

Verwendung von `omit-tools` (Denylist)

Alles außer den angegebenen Kategorien anzeigen — nützlich, wenn Sie die meisten Tools möchten, aber ein oder zwei ausblenden müssen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "omit-tools": "maintenance_windows,slo"
      }
    }
  }
}

Beide Header kombinieren

Zuerst eine Teilmenge auswählen, dann daraus entfernen:

{
  "mcpServers": {
    "Instana MCP Server": {
      "httpURL": "http://localhost:8080/mcp/",
      "headers": {
        "instana-base-url": "https://your-instana-instance.example.com",
        "instana-api-token": "YOUR_API_TOKEN",
        "select-tools": "app,infra,events,website",
        "omit-tools": "website"
      }
    }
  }
}

Der Server filtert die Antwort tools/list für diese Client-Verbindung bei jeder Anfrage — alle anderen Clients, die sich mit demselben Serverprozess verbinden, sind nicht betroffen.

Unbekannte Kategorienamen werden als Warnungen protokolliert und stillschweigend ignoriert.
Wenn keiner der Header vorhanden ist, werden alle registrierten Tools zurückgegeben (Standardverhalten).
Diese Header haben im stdio-Modus keine Wirkung — verwenden Sie stattdessen die CLI-Flags --tools / --omit-tools.

Vorteile der Tool-Filterung

Leistung: Reduzierte Startzeit und Speicherverbrauch
Sicherheit: Beschränkung der Exposition auf nur notwendige APIs
Klarheit: Fokus auf spezifische Anwendungsfälle (z. B. nur Infrastruktur-Monitoring)
Ressourceneffizienz: Geringere CPU- und Netzwerknutzung

Für Verwendungsbeispiele und Prompts siehe Example Prompts

Docker-Deployment

Der MCP-Instana-Server kann für Produktionsumgebungen mit Docker bereitgestellt werden. Das Docker-Setup ist auf Sicherheit, Leistung und minimalen Ressourcenverbrauch optimiert.

Erstellen des Docker-Images

Voraussetzungen

Docker ist installiert und läuft
Zugriff auf den Projektquellcode

Erstellen und Ausführen

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

Der obige Befehl erstellt das Image anhand der Anweisungen in der Dockerfile. Der Standardport ist 8080 und der Transportmodus ist streamable-http

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

Wenn Sie einen benutzerdefinierten Port auf Ihrem Host verwenden möchten (z. B. 9000)

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

Verbindung zum mcp-instana-Container im Streamable-Modus

Angenommen, Sie haben Ihren Container mit dem folgenden Befehl gestartet: docker run -p 8080:8080 mcp-instana

Ihr MCP-Client würde sich mit dem Host-Port (8080) verbinden. Standardmäßig läuft der Container im Streamable-Modus.

Hier ist eine Beispielkonfiguration für Ihren 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"
      ]
    }
  }
}

Verbindung zu mcp-instana im stdio-Modus

Im stdio-Modus können Sie Ihren MCP-Client den Container starten und sich mit ihm verbinden lassen. Hier geben Sie explizit an, im stdio zu laufen, indem Sie einen Wert für das Flag --transport angeben.

Nachfolgend finden Sie eine Beispielkonfiguration:

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

Weitere Details finden Sie in der Docker-Bereitstellungsanleitung hier

Eine umfassende Docker-Dokumentation einschließlich Multi-Architektur-Builds, .dockerignore, bewährter Sicherheitspraktiken und Beispielen für die Produktionsbereitstellung finden Sie in DOCKER.md.

Allgemeine Probleme

GitHub Copilot
- Wenn bei GitHub Copilot Probleme auftreten, versuchen Sie, den Server in der Datei mcp.json zu starten/stoppen/neu zu starten, und lassen Sie jeweils nur einen Server laufen.
Zertifikatsprobleme
- Wenn Zertifikatsprobleme auftreten, wie z. B. [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
  - Prüfen Sie, ob Sie den Instana-API-Endpunkt mit curl oder wget bei aktivierter SSL-Verifizierung erreichen können.
    - Wenn das funktioniert, kann Ihre Python-Umgebung das Zertifikat möglicherweise nicht verifizieren und hat eventuell keinen Zugriff auf dieselben Zertifikate wie Ihre Shell oder Ihr System. Stellen Sie sicher, dass Ihre Python-Umgebung Systemzertifikate verwendet (macOS). Dies können Sie erreichen, indem Sie Zertifikate in Python installieren: /Applications/Python\ 3.13/Install\ Certificates.command
  - Wenn Sie den Endpunkt nicht mit SSL-Verifizierung erreichen können, versuchen Sie es ohne. Wenn das funktioniert, prüfen Sie die CA-Zertifikate Ihres Systems und stellen Sie sicher, dass sie aktuell sind.

IBM Instana MCP Server

Was kann man mit IBM Instana MCP machen?

Dokumentation

Inhaltsverzeichnis

MCP-Server für IBM Instana

Schnellzugriff

Architekturübersicht

Workflow

Voraussetzungen

Instana MCP-Server installieren

Option 1: Installation von PyPI (empfohlen)

Option 2: Entwicklungsinstallation

uv installieren

Umgebung einrichten

Header-basierte Authentifizierung für den Streamable-HTTP-Modus

1. API-Token-Authentifizierung (direkte API-Aufrufe)

2. Sitzungstoken-Authentifizierung (UI-initiierte Aufrufe)

3. JWT-Token-Authentifizierung (IBM-Plattform-Integration)

Lokalen MCP-Server starten

Server-Befehlsoptionen

Verwendung der CLI (PyPI-Installation)

Verwendung der Entwicklungsinstallation

Im Streamable-HTTP-Modus starten

Verwendung der CLI (PyPI-Installation)

Verwendung der Entwicklungsinstallation

Im Stdio-Modus starten

Verwendung der CLI (PyPI-Installation)

Verwendung der Entwicklungsinstallation

Tool-Kategorien

Verwendung der CLI (PyPI-Installation)

Verwendung der Entwicklungsinstallation

SSL-Zertifikatsprüfung

Verwendung der CLI-Option

Verwendung der Umgebungsvariable

Verwendung von config.yaml (SaaS-/Kubernetes-Deployments)

Verwendung eines benutzerdefinierten CA-Bundles

API-Aufruf-Timeout

Catalog-Antwort-Caching

Gecachte Catalog-Operationen

Caching konfigurieren (stdio-Modus)

Caching konfigurieren (streamable-http-Modus)

Verwendung von .bob/mcp.json (stdio-Modus)

Überprüfen des Serverstatus

Häufige Startprobleme

Einrichtung und Verwendung

Unterstützte MCP-Clients

Verbindung mit mehreren Instana MCP Servern

Verfügbare Tools

Tool-Filterung

Verwendungsbeispiele

Verwendung der CLI (PyPI-Installation)

Verwendung der Entwicklungsinstallation

Tool-Filterung im Stdio-Modus

Tool-Filterung über HTTP-Header (Streamable-HTTP-Modus)

Verwendung von select-tools (Allowlist)

Verwendung von omit-tools (Denylist)

Beide Header kombinieren

Vorteile der Tool-Filterung

Docker-Deployment

Erstellen des Docker-Images

Voraussetzungen

Erstellen und Ausführen

Verbindung zum mcp-instana-Container im Streamable-Modus

Verbindung zu mcp-instana im stdio-Modus

Allgemeine Probleme

Verwendung von `select-tools` (Allowlist)

Verwendung von `omit-tools` (Denylist)