IBM Instana MCP Server

oficial

El servidor MCP de IBM Instana permite una interacción fluida con la plataforma de observabilidad IBM Instana, permitiéndole acceder a datos de observabilidad en tiempo real directamente dentro de su flujo de trabajo de desarrollo.

GitHub

¿Qué puedes hacer con IBM Instana MCP?

Query Instana alerts — Ask for the latest alerts from Instana for a specific application and get a natural-language summary.
Manage applications and infrastructure — Retrieve application metrics, alert configs, settings, and infrastructure snapshots through the server's tools.
Track SLOs and releases — List SLO configurations and reports, or browse and manage release records with timezone handling.
Handle maintenance windows — Create, modify, close, and list maintenance windows, including template and ServiceNow integration support.
Monitor websites and mobile apps — Analyze website and mobile app performance metrics, beacons, and session replay data.
Filter enabled tool categories — Start the server with only the tool categories you need using the --tools option.

Documentación

🔒 SSL habilitado por defecto: A partir de esta versión 1.0.3, la verificación de certificados SSL está habilitada por defecto para todas las llamadas salientes a la API de Instana. Puede personalizar este comportamiento (deshabilitar, proporcionar un paquete de CA personalizado, etc.) mediante la opción de CLI, la variable de entorno o config.yaml. Consulte Verificación de certificados SSL para obtener todos los detalles.

Tabla de contenidos

Servidor MCP para IBM Instana

Servidor MCP para IBM Instana

Enlaces rápidos

Herramientas y ejemplos - Documentación completa de herramientas con ejemplos del mundo real
Política de privacidad - Información sobre el tratamiento de datos y la privacidad
Guía de despliegue con Docker - Despliegue completo con Docker, compilaciones multiarquitectura y configuración para producción

El servidor IBM Instana MCP permite una interacción fluida con la plataforma de observabilidad Instana, lo que le permite acceder a datos de observabilidad en tiempo real directamente dentro de su flujo de trabajo de desarrollo.

Actúa como un puente entre los clientes (como agentes de IA o herramientas personalizadas) y las API REST de Instana, convirtiendo las consultas de los usuarios en solicitudes a la API de Instana y formateando las respuestas en formatos estructurados y fáciles de consumir.

El servidor admite los modos de transporte Streamable HTTP y Stdio para lograr la máxima compatibilidad con diferentes clientes MCP. Para obtener más detalles, consulte la especificación de modos de transporte MCP.

Descripción general de la arquitectura

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

Flujo de trabajo

Considere un ejemplo sencillo: está utilizando un host MCP (como Claude Desktop, VS Code u otro cliente) conectado al servidor IBM Instana MCP. Cuando solicita información sobre las alertas de Instana, se produce el siguiente proceso:

El cliente MCP recupera la lista de herramientas disponibles del servidor IBM Instana MCP
Su consulta se envía al LLM junto con las descripciones de las herramientas
El LLM analiza las herramientas disponibles y selecciona la(s) adecuada(s) para recuperar las alertas de Instana
El cliente ejecuta la(s) herramienta(s) elegida(s) a través del servidor IBM Instana MCP
Los resultados (últimas alertas) se devuelven al LLM
El LLM formula una respuesta en lenguaje natural
La respuesta se le muestra a usted

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

Requisitos previos

python - versión 3.10 o superior
pip - versión 21.3 o superior (solo requerido para la instalación basada en pypi)
uv - versión 0.11.6 o superior (solo requerido para la instalación para desarrollo)

Instalación del servidor IBM Instana MCP

Opción 1: Instalar desde PyPI (recomendado)

La forma más sencilla de usar mcp-instana es instalarlo directamente desde PyPI:

pip install mcp-instana

Después de la instalación, puede ejecutar el servidor usando el comando mcp-instana directamente.

Opción 2: Instalación para desarrollo

Para desarrollo o personalización local, puede clonar y configurar el proyecto localmente.

Instalación de uv

Este proyecto utiliza uv, un instalador y resolutor de paquetes de Python rápido. Para instalar uv, tiene varias opciones:

Uso de pip:

pip install uv

Uso de Homebrew (macOS):

brew install uv

Para obtener más opciones de instalación e instrucciones detalladas, visite la documentación de uv.

Configuración del entorno

Después de instalar uv, configure el entorno del proyecto ejecutando:

uv sync

Autenticación basada en encabezados para el modo Streamable HTTP

Cuando utilice el modo Streamable HTTP, debe pasar las credenciales de Instana a través de encabezados HTTP. Este enfoque mejora la seguridad y la flexibilidad al:

Evitar el almacenamiento de credenciales en variables de entorno
Permitir el uso de diferentes credenciales para diferentes solicitudes
Admitir entornos compartidos donde la modificación de variables de entorno está restringida
Admitir tanto la autenticación con token de API como la basada en sesión

Modos de autenticación compatibles:

1. Autenticación con token de API (llamadas directas a la API)

Encabezados requeridos:

instana-base-url: La URL de su instancia de Instana
instana-api-token: Su token de API de Instana

Ejemplo:

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

2. Autenticación con token de sesión (llamadas iniciadas desde la UI)

Encabezados requeridos:

instana-base-url: La URL de su instancia de Instana
instana-auth-token: Token de autenticación de sesión del backend de la UI
instana-csrf-token: Token CSRF del backend de la UI
instana-cookie-name: (Opcional) Nombre de la cookie para la autenticación de sesión (predeterminado: instanaAuthToken)

Ejemplo:

--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. Autenticación con token JWT (integración con IBM Platform)

Encabezados requeridos:

instana-base-url: La URL de su instancia de Instana
instana-jwt-token: Token JWT de IBM Platform
instana-csrf-token: Token CSRF para la validación de solicitudes

Ejemplo de configuración:

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

Prioridad de autenticación:

Token JWT (si se proporciona con el token CSRF) - Tiene prioridad para la integración con IBM Platform
Tokens de sesión (si se proporcionan tanto auth_token como csrf_token)
Token de API (si se proporciona) - Autenticación estándar
Variable de entorno (INSTANA_API_TOKEN) - Alternativa

Flujo de autenticación:

Los encabezados HTTP deben estar presentes en cada solicitud
El servidor valida las credenciales según el orden de prioridad
Las solicitudes sin autenticación válida fallarán

Este diseño garantiza una transmisión segura de las credenciales y admite múltiples flujos de autenticación, incluidas las llamadas iniciadas desde la UI a través de WebSocket → Coordinator → MCP Server.

Asegúrese de que el token utilizado tenga los permisos necesarios para invocar las herramientas MCP. Consulte aquí para obtener más información.

Inicio del servidor MCP local

Antes de configurar cualquier cliente MCP (Claude Desktop, GitHub Copilot o clientes MCP personalizados), debe iniciar el servidor MCP local. El servidor admite dos modos de transporte: Streamable HTTP y Stdio.

Opciones del comando del servidor

Uso de la CLI (instalación desde PyPI)

Si instaló mcp-instana desde PyPI, use el comando mcp-instana:

mcp-instana [OPTIONS]

Uso de la instalación para desarrollo

Para desarrollo local, use el comando uv run:

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

Opciones disponibles:

--transport <mode>: Modo de transporte (opciones: streamable-http, stdio)
--debug: Habilitar el modo de depuración con registro adicional
--log-level <level>: Establecer el nivel de registro (opciones: DEBUG, INFO, WARNING, ERROR, CRITICAL)
--tools <categories>: Lista separada por comas de categorías de herramientas a habilitar (p. ej., infra,app,events,website). Habilitar una categoría también habilitará sus prompts relacionados. Por ejemplo: --tools infra habilita las herramientas de infra y todos los prompts relacionados con infra.
--list-tools: Listar todas las categorías de herramientas disponibles y salir
--port <port>: Puerto del servidor MCP (predeterminado: 8080, se puede sobrescribir con la variable de entorno PORT)
--admin-port <port>: Puerto del servidor de administración para comprobaciones de estado (predeterminado: 8601, se puede sobrescribir con la variable de entorno ADMIN_PORT)
--verify-ssl [BOOL]: Habilitar o deshabilitar la verificación de certificados SSL para las llamadas salientes a la API de Instana (predeterminado: true). Pase false/0/no para deshabilitarla. Equivalente a establecer INSTANA_SSL_VERIFY=false.
--stream-read-buffer-size <SIZE>: Bytes por llamada de lectura de E/S utilizados por los analizadores de streaming (predeterminado: 65536 / 64k). Acepta un número de bytes simple o un sufijo legible: 64k, 64kb, 64m, 64mb, 64g, 64gb. También se puede establecer mediante la variable de entorno STREAM_READ_BUFFER_SIZE.
--help: Mostrar el mensaje de ayuda y salir

Inicio en modo Streamable HTTP

El modo Streamable HTTP proporciona una interfaz de API REST y se recomienda para la mayoría de los casos de uso.

Uso de la CLI (instalación desde PyPI)

# 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

Uso de la instalación para desarrollo

# 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

Características clave del modo Streamable HTTP:

Utiliza encabezados HTTP para la autenticación (no se necesitan variables de entorno)
Admite diferentes credenciales por solicitud
Más adecuado para entornos compartidos
Puerto predeterminado del servidor MCP: 8080
Endpoint MCP: http://0.0.0.0:8080/mcp/

Inicio en modo Stdio

El modo Stdio utiliza la entrada/salida estándar para la comunicación y requiere variables de entorno para la autenticación.

Uso de la CLI (instalación desde PyPI)

# 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

Uso de la instalación para desarrollo

# 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

Características clave del modo Stdio:

Utiliza variables de entorno para la autenticación (se pueden establecer mediante export o el archivo .env)
Comunicación directa mediante stdin/stdout
Requerido para ciertas configuraciones de clientes MCP

Categorías de herramientas

Puede optimizar el rendimiento del servidor habilitando solo las categorías de herramientas y prompts que necesite:

Uso de la CLI (instalación desde PyPI)

# 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

Uso de la instalación para desarrollo

# 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

Verificación de certificados SSL

La verificación de certificados SSL para las llamadas salientes a la API de Instana está habilitada por defecto. Esto se aplica tanto al modo de transporte Streamable HTTP como al modo Stdio.

Para deshabilitar la verificación de certificados SSL (por ejemplo, para entornos con certificados autofirmados o internos), use la opción de CLI --verify-ssl, la variable de entorno INSTANA_SSL_VERIFY o la clave sslVerify en config.yaml.

Uso de la opción de CLI

# 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

Uso de la variable de entorno

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

La verificación SSL se desactiva cuando INSTANA_SSL_VERIFY se establece en 0, false o no (sin distinguir mayúsculas y minúsculas). Cualquier otro valor, o cuando la variable no está definida, mantiene la verificación habilitada.

Uso de config.yaml (implementaciones SaaS / Kubernetes)

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

La clave sslVerify es leída por start.sh al iniciar y se exporta como INSTANA_SSL_VERIFY.

Uso de un paquete de CA personalizado

Cuando la verificación SSL está habilitada, se utiliza el paquete de CA del sistema de forma predeterminada. Para usar un paquete de certificados de CA personalizado, establezca 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 solo se utiliza cuando la verificación de certificados SSL está habilitada.

El servidor registra en el log el estado efectivo de la verificación SSL al iniciar, por lo que puede confirmar de inmediato si se ha detectado su variable de entorno, indicador de CLI o configuración del archivo de configuración.

Tiempo de espera de llamadas a la API

Cada llamada saliente a la API de Instana está sujeta a un tiempo de espera máximo estricto. Si el servidor de Instana no responde dentro del plazo, la llamada se cancela y se devuelve un error de inmediato — sin solicitudes que queden colgadas indefinidamente.

El tiempo de espera predeterminado es de 180 segundos. Anúlelo con la variable de entorno INSTANA_API_TIMEOUT:

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

INSTANA_API_TIMEOUT debe ser un entero positivo (segundos). Los valores no enteros o no positivos se ignoran y se utiliza el valor predeterminado de 180 segundos.

Almacenamiento en caché de respuestas del catálogo

El servidor almacena en caché las respuestas de la API de catálogo (métricas, etiquetas y plugins) en el proceso para eliminar viajes de ida y vuelta redundantes. Los datos del catálogo son estables dentro de un inquilino — solo cambian cuando se implementan nuevas integraciones — por lo que las respuestas se pueden reutilizar de forma segura durante la vida útil de un único proceso del servidor.

TTL predeterminado: 30 minutos. Cada combinación única de URL de inquilino, método y parámetros obtiene su propia ranura de caché independiente. Las respuestas de error nunca se almacenan en caché, por lo que un fallo de red transitorio no puede contaminar el almacén.

Operaciones de catálogo en caché

Dominio	Operación	Discriminadores de clave de caché
Aplicación	Obtener catálogo de métricas	—
Aplicación	Obtener catálogo de etiquetas	`use_case`, `data_source`
Sitio web	Obtener catálogo de métricas	—
Sitio web	Obtener catálogo de etiquetas	`beacon_type`, `use_case`
Aplicación móvil	Obtener catálogo de métricas	—
Aplicación móvil	Obtener catálogo de etiquetas	`beacon_type`, `use_case`
Sintético	Obtener catálogo de métricas	—
Sintético	Obtener catálogo de etiquetas	`use_case`
Infraestructura	Obtener catálogo de métricas	`plugin`, `filter`
Infraestructura	Obtener catálogo de etiquetas	`plugin`

Configuración del almacenamiento en caché (modo stdio)

Establezca las variables de entorno antes de iniciar el servidor. En modo stdio estos son los únicos valores utilizados — no se requiere reiniciar cuando se usa Bob, ya que el servidor se reinicia automáticamente.

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

INSTANA_CACHE_ENABLED se considera deshabilitado cuando se establece en false, 0 o no (sin distinguir mayúsculas y minúsculas). Cualquier otro valor mantiene el almacenamiento en caché habilitado.

Configuración del almacenamiento en caché (modo streamable-http)

Además de las variables de entorno anteriores, cada solicitud HTTP puede anular la configuración de caché mediante encabezados. Los encabezados por solicitud tienen prioridad sobre los valores predeterminados a nivel de proceso, por lo que el almacenamiento en caché se puede activar o desactivar sin reiniciar el servidor.

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

Para establecer encabezados de caché de forma persistente en la configuración de su cliente MCP (por ejemplo, .bob/mcp.json para el modo streamable-http), agréguelos junto a los encabezados de Instana existentes:

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

Para deshabilitar el almacenamiento en caché para una conexión de cliente específica:

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

Uso de .bob/mcp.json (modo stdio)

Para establecer la configuración de caché de forma persistente para Bob, agregue las variables de entorno al bloque env en .bob/mcp.json:

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

El servidor registra el estado efectivo de la caché a nivel DEBUG en cada llamada al catálogo, mostrando si una respuesta fue un HIT o MISS de caché.

Verificación del estado del servidor

Una vez iniciado, puede verificar que el servidor está en ejecución:

Para el modo Streamable HTTP:

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

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

Para el modo Stdio: El servidor se iniciará y esperará la entrada de stdin de los clientes MCP.

Problemas comunes de inicio

Problemas de SSL / Certificados: Consulte la sección Verificación de certificados SSL anterior para las opciones de configuración. Si encuentra errores SSL con la verificación habilitada y está usando macOS, asegúrese de que su entorno de Python tenga acceso a los certificados del sistema:

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

Puerto ya en uso: Si el puerto 8080 ya está en uso, especifique un puerto diferente:

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

Dependencias faltantes: Asegúrese de que todas las dependencias estén instaladas:

uv sync

Configuración y uso

Clientes MCP compatibles

Cliente	Transportes
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`

Conexión a varios servidores MCP de Instana

Puede configurar su cliente MCP para conectarse a varias instancias. A continuación se muestra una configuración de ejemplo:

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

Para dirigirse a un servidor específico, asegúrese de que:

El servidor esté configurado con el nombre de entorno adecuado en la configuración de MCP (por ejemplo, Instana MCP Server1)
El prompt mencione explícitamente el nombre del servidor/entorno.

La solicitud se enrutará entonces al servidor configurado correspondiente. Si no se menciona explícitamente ningún servidor/entorno en el prompt, MCP utiliza el primer servidor definido en la configuración como servidor predeterminado.

Nota: Si el servidor solicitado está caído o no es accesible, MCP se comporta según lo esperado y reenvía el fallo de la API. El usuario recibirá el error correspondiente devuelto por la API, indicando que el servidor no está disponible. MCP depende de la disponibilidad de la API subyacente y no realiza conmutación por error automática.

Herramientas disponibles

Herramienta	Categoría	Descripción
`manage_applications`	Aplicación e Infraestructura	Herramienta unificada para gestionar métricas de aplicaciones, configuraciones de alertas, ajustes y catálogo
`manage_websites`	Monitoreo de sitios web	Enrutador inteligente unificado para operaciones de análisis, catálogo, configuración y configuración avanzada de sitios web
`manage_custom_dashboards`	Paneles personalizados	Herramienta unificada para gestionar operaciones CRUD de paneles personalizados
`manage_infrastructure`	Infraestructura	Enrutador inteligente unificado para análisis de infraestructura, catálogo (`get_plugin_schema`), configuraciones de alertas inteligentes y operaciones de recursos de instantáneas
`manage_automation`	Automatización	Enrutador inteligente unificado para automatización: explorar catálogo de acciones y ver historial de ejecuciones
`manage_events`	Eventos	Enrutador inteligente unificado para monitoreo de eventos: obtener evento por ID, obtener eventos por IDs, eventos de Kubernetes, eventos de monitoreo de agentes y todos los eventos
`manage_slo`	Gestión de SLO	Enrutador inteligente unificado para configuraciones de SLO, informes, alertas y ventanas de corrección con manejo inteligente de zonas horarias
`manage_releases`	Gestión de versiones	Enrutador inteligente unificado para seguimiento de versiones: listar versiones con paginación y filtrado por nombre, obtener detalles de versiones, crear/actualizar/eliminar versiones con soporte de zonas horarias
`manage_maintenance_windows`	Ventanas de mantenimiento	Enrutador inteligente unificado para la gestión del ciclo de vida de ventanas de mantenimiento: crear, modificar, cerrar y listar ventanas de mantenimiento con soporte de plantillas e integración con ServiceNow
`manage_mobile_apps`	Monitoreo de aplicaciones móviles	Enrutador inteligente unificado para monitoreo de aplicaciones móviles: analizar balizas, métricas de rendimiento, repetición de sesiones, configuración y gestión de alertas
`manage_synthetics`	Monitoreo sintético	Enrutador inteligente unificado para monitoreo sintético: catálogo, métricas, ajustes (solo lectura) y resultados de reproducción de pruebas

Para documentación detallada de herramientas, capacidades y referencia técnica, consulte Herramientas y ejemplos

Filtrado de herramientas

El servidor MCP admite la carga selectiva de herramientas para optimizar el rendimiento y reducir el uso de recursos. Puede habilitar solo las categorías de herramientas que necesita para su caso de uso específico.

Ejemplos de uso

Uso de la CLI (instalación de PyPI)

# 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

Uso de la instalación de desarrollo

# 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

Filtrado de herramientas en modo Stdio

En modo stdio, el cliente MCP inicia el servidor como un proceso hijo, por lo que los indicadores se pasan directamente a través del arreglo args en mcp.json.

Uso de --tools (lista de permitidos) — mostrar solo las categorías listadas:

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

Uso de --omit-tools (lista de denegados) — mostrar todo excepto las categorías listadas:

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

Combinando ambos — seleccionar un subconjunto y luego eliminar de él:

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

Filtrado de herramientas mediante encabezado HTTP (modo Streamable HTTP)

Cuando el servidor se ejecuta en modo streamable HTTP, cada cliente MCP puede controlar qué categorías de herramientas ve sin reiniciar el servidor ni ejecutar una instancia separada. Se admiten dos encabezados complementarios:

Encabezado	Comportamiento
`select-tools`	Lista de permitidos — mostrar solo las categorías listadas
`omit-tools`	Lista de denegados — mostrar todo excepto las categorías listadas

Ambos encabezados aceptan una lista separada por comas de nombres de categorías idénticos a los utilizados por los indicadores de CLI --tools / --omit-tools. Se pueden combinar: select-tools se aplica primero para construir el conjunto visible, luego omit-tools elimina de él.

Uso de `select-tools` (lista de permitidos)

Mostrar solo las categorías especificadas:

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

Uso de `omit-tools` (lista de denegados)

Mostrar todo excepto las categorías especificadas — útil cuando desea la mayoría de las herramientas pero necesita ocultar una o dos:

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

Combinación de ambos encabezados

Seleccionar primero un subconjunto y luego eliminar de él:

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

El servidor filtra la respuesta tools/list para esa conexión de cliente en cada solicitud — todos los demás clientes que se conectan al mismo proceso del servidor no se ven afectados.

Los nombres de categorías desconocidos se registran como advertencias y se ignoran silenciosamente.
Si ninguno de los encabezados está presente, se devuelven todas las herramientas registradas (comportamiento predeterminado).
Estos encabezados no tienen efecto en modo stdio — utilice los indicadores de CLI --tools / --omit-tools en su lugar.

Beneficios del filtrado de herramientas

Rendimiento: Menor tiempo de inicio y uso de memoria
Seguridad: Limitar la exposición solo a las API necesarias
Claridad: Centrarse en casos de uso específicos (por ejemplo, solo monitoreo de infraestructura)
Eficiencia de recursos: Menor uso de CPU y red

Para ejemplos de uso y prompts, consulte Prompts de ejemplo

Implementación con Docker

El servidor MCP de Instana se puede desplegar usando Docker para entornos de producción. La configuración de Docker está optimizada para la seguridad, el rendimiento y el uso mínimo de recursos.

Construcción de la imagen Docker

Requisitos previos

Docker instalado y en ejecución
Acceso al código fuente del proyecto

Construir y ejecutar

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

El comando anterior construirá la imagen usando las instrucciones del Dockerfile. El puerto predeterminado es 8080 y el modo de transporte es streamable-http

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

Si deseas usar un puerto personalizado en tu host (ej.: 9000)

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

Conexión al contenedor mcp-instana en modo streamable

Suponiendo que iniciaste tu contenedor usando el comando: docker run -p 8080:8080 mcp-instana

Tu cliente MCP se conectaría al puerto del host (8080). De forma predeterminada, el contenedor se ejecuta en modo streamable.

Aquí tienes una configuración de ejemplo para tu cliente MCP:

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

Conexión a mcp-instana en modo stdio

En el modo stdio, puedes hacer que tu cliente MCP inicie y se conecte al contenedor. Aquí estás especificando explícitamente que se ejecute en stdio proporcionando un valor para el flag --transport.

A continuación se muestra una configuración de ejemplo:

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

Para más detalles, consulta la guía de despliegue con Docker aquí

Para obtener documentación completa sobre Docker, incluidos builds multiarquitectura, .dockerignore, buenas prácticas de seguridad y ejemplos de despliegue en producción, consulta DOCKER.md.

Problemas generales

GitHub Copilot
- Si encuentras problemas con GitHub Copilot, intenta iniciar/detener/reiniciar el servidor en el archivo mcp.json y mantén solo un servidor en ejecución a la vez.
Problemas de certificados
- Si encuentras problemas de certificados, como [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
  - Comprueba que puedes alcanzar el endpoint de la API de Instana usando curl o wget con verificación SSL.
    - Si eso funciona, es posible que tu entorno de Python no pueda verificar el certificado y que no tenga acceso a los mismos certificados que tu shell o sistema. Asegúrate de que tu entorno de Python use los certificados del sistema (macOS). Puedes hacerlo instalando certificados en Python: /Applications/Python\ 3.13/Install\ Certificates.command
  - Si no puedes alcanzar el endpoint con verificación SSL, prueba sin ella. Si eso funciona, revisa los certificados CA de tu sistema y asegúrate de que estén actualizados.

IBM Instana MCP Server

¿Qué puedes hacer con IBM Instana MCP?

Documentación

Tabla de contenidos

Servidor MCP para IBM Instana

Enlaces rápidos

Descripción general de la arquitectura

Flujo de trabajo

Requisitos previos

Instalación del servidor IBM Instana MCP

Opción 1: Instalar desde PyPI (recomendado)

Opción 2: Instalación para desarrollo

Instalación de uv

Configuración del entorno

Autenticación basada en encabezados para el modo Streamable HTTP

1. Autenticación con token de API (llamadas directas a la API)

2. Autenticación con token de sesión (llamadas iniciadas desde la UI)

3. Autenticación con token JWT (integración con IBM Platform)

Inicio del servidor MCP local

Opciones del comando del servidor

Uso de la CLI (instalación desde PyPI)

Uso de la instalación para desarrollo

Inicio en modo Streamable HTTP

Uso de la CLI (instalación desde PyPI)

Uso de la instalación para desarrollo

Inicio en modo Stdio

Uso de la CLI (instalación desde PyPI)

Uso de la instalación para desarrollo

Categorías de herramientas

Uso de la CLI (instalación desde PyPI)

Uso de la instalación para desarrollo

Verificación de certificados SSL

Uso de la opción de CLI

Uso de la variable de entorno

Uso de config.yaml (implementaciones SaaS / Kubernetes)

Uso de un paquete de CA personalizado

Tiempo de espera de llamadas a la API

Almacenamiento en caché de respuestas del catálogo

Operaciones de catálogo en caché

Configuración del almacenamiento en caché (modo stdio)

Configuración del almacenamiento en caché (modo streamable-http)

Uso de .bob/mcp.json (modo stdio)

Verificación del estado del servidor

Problemas comunes de inicio

Configuración y uso

Clientes MCP compatibles

Conexión a varios servidores MCP de Instana

Herramientas disponibles

Filtrado de herramientas

Ejemplos de uso

Uso de la CLI (instalación de PyPI)

Uso de la instalación de desarrollo

Filtrado de herramientas en modo Stdio

Filtrado de herramientas mediante encabezado HTTP (modo Streamable HTTP)

Uso de select-tools (lista de permitidos)

Uso de omit-tools (lista de denegados)

Combinación de ambos encabezados

Beneficios del filtrado de herramientas

Implementación con Docker

Construcción de la imagen Docker

Requisitos previos

Construir y ejecutar

Conexión al contenedor mcp-instana en modo streamable

Conexión a mcp-instana en modo stdio

Problemas generales

Uso de `select-tools` (lista de permitidos)

Uso de `omit-tools` (lista de denegados)