IBM Instana MCP Server

oficial

O servidor MCP IBM Instana permite interação contínua com a plataforma de observabilidade IBM Instana, possibilitando o acesso a dados de observabilidade em tempo real diretamente no seu fluxo de trabalho de desenvolvimento.

GitHub

Experimente este MCPPatrocinado

O que você pode fazer com IBM Instana MCP?

Consultar desempenho de aplicações — Solicite métricas de aplicação, alertas ou detalhes de catálogo usando ferramentas da categoria app, como get_app_metrics ou get_app_alerts.
Monitorar saúde da infraestrutura — Recupere recursos de infraestrutura, topologia e métricas por meio de ferramentas infra, como get_infra_metrics ou get_infra_topology.
Acompanhar eventos e incidentes — Acesse eventos do Kubernetes ou dados de monitoramento de agentes com ferramentas events, como get_k8s_events ou get_agent_status.
Analisar monitoramento de sites — Obtenha métricas de sites, informações de catálogo ou configuração usando ferramentas website, como get_website_metrics ou get_website_config.
Filtrar ferramentas por categoria — Ative apenas as categorias de ferramentas necessárias na inicialização com a flag --tools (ex.: --tools infra,events) para otimizar o desempenho.

Documentação

Sumário

Servidor MCP para IBM Instana

Servidor MCP para IBM Instana

📚 Links Rápidos

Ferramentas e Exemplos - Documentação abrangente de ferramentas com exemplos do mundo real
Política de Privacidade - Informações sobre tratamento de dados e privacidade
Guia de Implantação com Docker - Implantação abrangente com Docker, builds multi-arquitetura e configuração de produção

O servidor MCP do Instana permite interação perfeita com a plataforma de observabilidade do Instana, permitindo que você acesse dados de observabilidade em tempo real diretamente no seu fluxo de trabalho de desenvolvimento.

Ele atua como uma ponte entre clientes (como agentes de IA ou ferramentas personalizadas) e as APIs REST do Instana, convertendo consultas de usuários em solicitações de API do Instana e formatando as respostas em formatos estruturados e facilmente consumíveis.

O servidor suporta os modos de transporte HTTP Streamable e Stdio para máxima compatibilidade com diferentes clientes MCP. Para mais detalhes, consulte a especificação de Modos de Transporte MCP.

Visão Geral da Arquitetura

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

Fluxo de Trabalho

Considere um exemplo simples: você está usando um Host MCP (como Claude Desktop, VS Code ou outro cliente) conectado ao Servidor MCP do Instana. Quando você solicita informações sobre alertas do Instana, o seguinte processo ocorre:

O cliente MCP recupera a lista de ferramentas disponíveis no servidor MCP do Instana
Sua consulta é enviada ao LLM junto com as descrições das ferramentas
O LLM analisa as ferramentas disponíveis e seleciona a(s) apropriada(s) para recuperar alertas do Instana
O cliente executa a(s) ferramenta(s) escolhida(s) por meio do servidor MCP do Instana
Os resultados (alertas mais recentes) são retornados ao LLM
O LLM formula uma resposta em linguagem natural
A resposta é exibida para você

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

Pré-requisitos

Opção 1: Instalar a partir do PyPI (Recomendado)

A maneira mais fácil de usar o mcp-instana é instalá-lo diretamente do PyPI:

pip install mcp-instana

Após a instalação, você pode executar o servidor usando o comando mcp-instana diretamente.

Opção 2: Instalação para Desenvolvimento

Para desenvolvimento ou personalização local, você pode clonar e configurar o projeto localmente.

Instalando o uv

Este projeto usa uv, um instalador e resolvedor de pacotes Python rápido. Para instalar o uv, você tem várias opções:

Usando pip:

pip install uv

Usando Homebrew (macOS):

brew install uv

Para mais opções de instalação e instruções detalhadas, visite a documentação do uv.

Configurando o Ambiente

Após instalar o uv, configure o ambiente do projeto executando:

uv sync

Autenticação Baseada em Cabeçalhos para o Modo HTTP Streamable

Ao usar o modo HTTP Streamable, você deve passar as credenciais do Instana por meio de cabeçalhos HTTP. Essa abordagem aumenta a segurança e a flexibilidade ao:

Evitar o armazenamento de credenciais em variáveis de ambiente
Permitir o uso de credenciais diferentes para solicitações diferentes
Suportar ambientes compartilhados onde a modificação de variáveis de ambiente é restrita
Suportar autenticação baseada em token de API e em sessão

Modos de Autenticação Suportados:

1. Autenticação por Token de API (Chamadas Diretas à API)

Cabeçalhos Necessários:

instana-base-url: A URL da sua instância do Instana
instana-api-token: Seu token de API do Instana

Exemplo:

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

2. Autenticação por Token de Sessão (Chamadas Iniciadas pela Interface)

Cabeçalhos Necessários:

instana-base-url: A URL da sua instância do Instana
instana-auth-token: Token de autenticação de sessão do backend da interface
instana-csrf-token: Token CSRF do backend da interface
instana-cookie-name: (Opcional) Nome do cookie para autenticação de sessão (padrão: instanaAuthToken)

Exemplo:

--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. Autenticação por Token JWT (Integração com a Plataforma IBM)

Cabeçalhos Necessários:

instana-base-url: A URL da sua instância do Instana
instana-jwt-token: Token JWT da Plataforma IBM
instana-csrf-token: Token CSRF para validação de solicitações

Exemplo de Configuração:

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

Prioridade de Autenticação:

Token JWT (se fornecido com token CSRF) - Tem precedência para integração com a Plataforma IBM
Tokens de Sessão (se auth_token e csrf_token forem fornecidos)
Token de API (se fornecido) - Autenticação padrão
Variável de Ambiente (INSTANA_API_TOKEN) - Fallback

Fluxo de Autenticação:

Os cabeçalhos HTTP devem estar presentes em cada solicitação
O servidor valida as credenciais com base na ordem de prioridade
Solicitações sem autenticação válida falharão

Este design garante a transmissão segura de credenciais e suporta múltiplos fluxos de autenticação, incluindo chamadas iniciadas pela interface via WebSocket → Coordinator → MCP Server.

Garanta que o token usado tenha as permissões necessárias para invocar as ferramentas MCP. Verifique aqui para mais informações.

Iniciando o Servidor MCP Local

Antes de configurar qualquer cliente MCP (Claude Desktop, GitHub Copilot ou clientes MCP personalizados), você precisa iniciar o servidor MCP local. O servidor suporta dois modos de transporte: HTTP Streamable e Stdio.

Opções de Comando do Servidor

Usando a CLI (Instalação via PyPI)

Se você instalou o mcp-instana a partir do PyPI, use o comando mcp-instana:

mcp-instana [OPTIONS]

Usando a Instalação para Desenvolvimento

Para desenvolvimento local, use o comando uv run:

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

Opções Disponíveis:

--transport <mode>: Modo de transporte (opções: streamable-http, stdio)
--env KEY=VALUE: Definir variável de ambiente (pode ser repetido para múltiplas variáveis, ex.: --env INSTANA_BASE_URL=https://... --env INSTANA_API_TOKEN=...)
--debug: Ativar modo de depuração com registro adicional
--log-level <level>: Definir o nível de registro (opções: DEBUG, INFO, WARNING, ERROR, CRITICAL)
--tools <categories>: Lista separada por vírgulas de categorias de ferramentas a ativar (ex.: infra,app,events,website). Ativar uma categoria também ativará seus prompts relacionados. Por exemplo: --tools infra ativa as ferramentas de infraestrutura e todos os prompts relacionados à infraestrutura.
--list-tools: Listar todas as categorias de ferramentas disponíveis e sair
--port <port>: Porta do servidor MCP (padrão: 8080, pode ser substituída pela variável de ambiente PORT)
--verify-ssl: Ativar verificação de certificado SSL para chamadas de API do Instana de saída. Equivalente a definir INSTANA_SSL_VERIFY=true. A verificação SSL está desativada por padrão.
--help: Mostrar mensagem de ajuda e sair

Iniciando no Modo HTTP Streamable

O modo HTTP Streamable fornece uma interface de API REST e é recomendado para a maioria dos casos de uso.

Usando a CLI (Instalação via 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

Usando a Instalação para Desenvolvimento

# 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

Principais Recursos do Modo HTTP Streamable:

Usa cabeçalhos HTTP para autenticação (sem necessidade de variáveis de ambiente)
Suporta credenciais diferentes por solicitação
Mais adequado para ambientes compartilhados
Porta padrão do servidor MCP: 8080
Endpoint MCP: http://0.0.0.0:8080/mcp/

Iniciando no Modo Stdio

O modo Stdio usa entrada/saída padrão para comunicação e requer variáveis de ambiente para autenticação.

Usando a CLI (Instalação via PyPI)

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
mcp-instana

# Or explicitly specify stdio mode
mcp-instana --transport stdio

# Option 2: Use --env flag to set environment variables directly
mcp-instana --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
mcp-instana --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Usando a Instalação para Desenvolvimento

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
uv run src/core/server.py

# Or explicitly specify stdio mode
uv run src/core/server.py --transport stdio

# Option 2: Use --env flag to set environment variables directly
uv run src/core/server.py --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
uv run src/core/server.py --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Principais Recursos do Modo Stdio:

Usa variáveis de ambiente para autenticação (podem ser definidas via export ou pela flag --env)
Comunicação direta via stdin/stdout
Necessário para certas configurações de clientes MCP
A flag --env fornece uma maneira conveniente de definir credenciais sem modificar o ambiente do shell

Categorias de Ferramentas

Você pode otimizar o desempenho do servidor ativando apenas as categorias de ferramentas e prompts que precisa:

Usando a CLI (Instalação via 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

Usando a Instalação para Desenvolvimento

# 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

Categorias Disponíveis:

infra: Ferramentas e prompts de monitoramento de infraestrutura (recursos, catálogo, topologia, análise, métricas)
app: Ferramentas e prompts de desempenho de aplicações (recursos, métricas, alertas, catálogo, topologia, análise, configurações, alertas globais)
events: Ferramentas e prompts de monitoramento de eventos (eventos Kubernetes, monitoramento de agentes)
website: Ferramentas e prompts de monitoramento de websites (métricas, catálogo, análise, configuração)

Verificação de Certificado SSL

A verificação de certificado SSL para chamadas de API do Instana de saída está desativada por padrão. Isso se aplica aos modos de transporte HTTP Streamable e Stdio.

Para ativar a verificação de certificado SSL, use a opção --verify-ssl da CLI ou a variável de ambiente INSTANA_SSL_VERIFY.

Usando a opção de CLI

uv run src/core/server.py --verify-ssl

A opção --verify-ssl é equivalente a definir:

export INSTANA_SSL_VERIFY=true

Usando a variável de ambiente

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

A verificação SSL é desabilitada quando INSTANA_SSL_VERIFY está definido como 0, false ou no (sem diferenciar maiúsculas de minúsculas), ou quando não está definido. Qualquer outro valor ativa a verificação — use true, 1 ou yes como as opções convencionais.

Usando um pacote de certificados CA personalizado

Quando a verificação SSL está ativada, o pacote de certificados CA do sistema é usado por padrão. Para usar um pacote de certificados CA personalizado, defina 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 só é usado quando a verificação de certificado SSL está ativada.

O servidor registra o estado efetivo da verificação SSL na inicialização, para que você possa confirmar imediatamente se a variável de ambiente ou a flag de CLI foi aplicada.

Verificando o Status do Servidor

Após a inicialização, você pode verificar se o servidor está em execução:

Para o 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 o modo Stdio: O servidor iniciará e aguardará a entrada stdin dos clientes MCP.

Problemas Comuns de Inicialização

Problemas de SSL / Certificados: Consulte a seção Verificação de Certificado SSL acima para opções de configuração. Se você encontrar erros de SSL com a verificação ativada e estiver usando macOS, garanta que seu ambiente Python tenha acesso aos certificados do sistema:

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

Porta Já em Uso: Se a porta 8080 já estiver em uso, especifique uma porta diferente:

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

Dependências Ausentes: Garanta que todas as dependências estejam instaladas:

uv sync

Configuração e Uso

Bob IDE

Bob é o IDE com IA da IBM que suporta nativamente a integração MCP. O Bob oferece uma experiência de desenvolvimento integrada com assistência de IA e ferramentas de observabilidade.

Modo Streamable HTTP

O modo Streamable HTTP fornece uma interface de API REST para comunicação MCP usando JSON-RPC sobre HTTP.

Passo 1: Inicie o Servidor MCP no Modo Streamable HTTP

Antes de configurar o Bob, você precisa iniciar o servidor MCP no modo Streamable HTTP. Consulte a seção Iniciando o Servidor MCP Local para instruções detalhadas.

Passo 2: Configure o Bob

No canto superior direito do painel do Bob, você verá um menu suspenso com os servidores MCP:

Ao selecioná-lo, você deverá ver a opção de configurar o MCP no nível do projeto ou no nível global.

Escopos de Configuração MCP

O Bob suporta dois níveis de configuração MCP, permitindo que você escolha o escopo que melhor atende ao seu caso de uso:

1. Configuração Global (Nível do Usuário)

A configuração global aplica servidores MCP em todos os projetos do usuário atual. Isso é ideal quando você deseja que os mesmos servidores MCP estejam disponíveis em todos os projetos em que trabalha.

Locais dos Arquivos:

macOS: ~/Library/Application Support/Bob/bob_config.json
Windows: %APPDATA%\Bob\bob_config.json
Linux: ~/.config/Bob/bob_config.json

2. Configuração do Projeto (Nível do Projeto)

A configuração do projeto aplica servidores MCP apenas a um projeto específico. Isso é útil quando diferentes projetos exigem configurações de servidor MCP diferentes ou quando você deseja compartilhar configurações MCP com sua equipe por meio do controle de versão.

Local do Arquivo:

.bob/bob_config.json no diretório raiz do seu projeto

Escolhendo entre Configuração Global e do Projeto:

Use a configuração global para servidores MCP que você deseja disponibilizar em todos os seus projetos
Use a configuração do projeto para servidores MCP específicos do projeto ou para compartilhar configurações com sua equipe
Ambas as configurações podem coexistir — as configurações no nível do projeto têm precedência sobre as configurações globais para o mesmo nome de servidor

Para mais informações sobre o Bob e a configuração MCP, visite: https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

Configuração Local:

Configure o Bob para conectar ao seu servidor MCP Instana local:

{
  "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-api-token: your_instana_api_token"
      ]
    }
  }
}

Configuração Remota:

Configure o Bob para conectar a um servidor MCP Instana remoto (por exemplo, implantado no IBM Code Engine):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://app-instana-750.1zetetanw8ul.us-east.codeengine.appdomain.cloud/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Nota: Para usar o npx, recomendamos primeiro instalar o NVM (Node Version Manager) e, em seguida, usá-lo para instalar o Node.js. As instruções de instalação estão disponíveis em: https://nodejs.org/en/download

Passo 3: Teste a Conexão

Depois de configurar o MCP, o servidor MCP recém-configurado deve aparecer como ativado. Um ponto verde indica que o servidor está em execução com sucesso.

Agora você pode executar consultas no Bob IDE:

get me all applications from Instana in the last 24 hours

Modo Stdio

Configuração usando CLI (Instalação via PyPI — Recomendado):

Opção 1: Usando variáveis de ambiente na configuração:

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

Opção 2: Usando a flag --env (método alternativo):

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

Nota: Se você encontrar erros de "comando não encontrado", use o caminho completo para o mcp-instana. Encontre-o com which mcp-instana e use esse caminho.

Configuração usando Instalação de Desenvolvimento:

Opção 1: Usando variáveis de ambiente na configuração:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Opção 2: Usando a flag --env (método alternativo):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Claude Desktop

O Claude Desktop suporta os modos Streamable HTTP e Stdio para integração MCP.

Configure o Claude Desktop editando o arquivo de configuração:

Locais dos Arquivos:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Modo Streamable HTTP

O modo Streamable HTTP fornece uma interface de API REST para comunicação MCP usando JSON-RPC sobre HTTP.

Passo 1: Inicie o Servidor MCP no Modo Streamable HTTP

Antes de configurar o Claude Desktop, você precisa iniciar o servidor MCP no modo Streamable HTTP. Consulte a seção Iniciando o Servidor MCP Local para instruções detalhadas.

Passo 2: Configure o Claude Desktop

Configure o Claude Desktop para passar as credenciais do Instana por meio de cabeçalhos:

{
  "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-api-token: your_instana_api_token"
      ]
    }
  }
}

Passo 3: Teste a Conexão

Reinicie o Claude Desktop. Agora você deve ver o Instana MCP Server na interface do Claude Desktop, conforme mostrado abaixo:

Agora você pode executar consultas no Claude Desktop:

get me all endpoints from Instana

Modo Stdio

Configuração usando CLI (Instalação via PyPI — Recomendado):

Opção 1: Usando variáveis de ambiente na configuração:

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

Opção 2: Usando a flag --env (método alternativo):

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

Nota: Se você encontrar erros de "comando não encontrado", use o caminho completo para o mcp-instana. Encontre-o com which mcp-instana e use esse caminho.

Configuração usando Instalação de Desenvolvimento:

Opção 1: Usando variáveis de ambiente na configuração:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Opção 2: Usando a flag --env (método alternativo):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Configuração do Kiro

O Kiro é um IDE agêntico, não uma extensão que pode ser baixada no VS Code ou em outro IDE.

Passo 1: Baixe e instale o Kiro para o seu sistema operacional em https://kiro.dev/.

Passo 2: Após a instalação, inicie o Kiro e abra qualquer projeto no IDE. alt text

Passo 3: Clique no ícone do Kiro (Fantasma) na barra lateral esquerda para acessar os recursos do Kiro. alt text

Passo 4: Selecione o ícone Editar Configuração no canto superior direito da seção Servidores MCP. alt text

Passo 5: Abra o arquivo de configuração do servidor MCP (mcp.json) e configure-o com base no modo de transporte preferido:

Modo Streamable HTTP (Recomendado para o Kiro)

{
  "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-api-token: your_instana_api_token"
      ]
    }
  }
}

Nota: Certifique-se de iniciar o servidor MCP no modo streamable-http antes de usar esta configuração:

mcp-instana --transport streamable-http

Modo Stdio

Opção 1: Usando variáveis de ambiente na configuração:

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

Opção 2: Usando a flag --env (método alternativo):

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

Passo 6: Após salvar o arquivo, clique no botão Ativar MCP e você verá seu servidor MCP e suas ferramentas disponíveis aparecerem na seção inferior esquerda do Kiro. alt text

Passo 7: Vá para o painel de Chat de IA, insira um prompt relacionado ao seu servidor MCP e visualize a resposta diretamente no Kiro. alt text

GitHub Copilot

O GitHub Copilot suporta integração MCP por meio da configuração do VS Code. Para a integração do GitHub Copilot com o VS Code, consulte este guia de configuração.

Modo Streamable HTTP

Passo 1: Inicie o Servidor MCP no Modo Streamable HTTP

Antes de configurar o VS Code, você precisa iniciar o servidor MCP no modo Streamable HTTP. Consulte a seção Iniciando o Servidor MCP Local para instruções detalhadas.

Passo 2: Configure o VS Code

Consulte Usar servidores MCP no VS Code para configuração detalhada.

Você pode criar ou atualizar diretamente o .vscode/mcp.json com a seguinte configuração:

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

Nota: Substitua os seguintes valores pela sua configuração real:

instana-base-url: A URL da sua instância do Instana
instana-api-token: Seu token de API do Instana
command: Atualize o caminho do npx para corresponder à instalação do Node.js do seu sistema (por exemplo, /path/to/your/node/bin/npx)
Variáveis de ambiente: ajuste o PATH e outras variáveis de ambiente conforme necessário para o seu sistema

Modo Stdio

Passo 1: Crie a Configuração MCP do VS Code

Usando CLI (Instalação via PyPI — Recomendado):

Crie o .vscode/mcp.json na raiz do seu projeto:

Opção 1: Usando variáveis de ambiente na configuração:

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

Opção 2: Usando a flag --env (método alternativo):

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

Usando Instalação de Desenvolvimento:

Crie o .vscode/mcp.json na raiz do seu projeto:

Opção 1: Usando variáveis de ambiente na configuração:

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Opção 2: Usando a flag --env (método alternativo):

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Nota: Substitua os seguintes valores pela sua configuração real:

Para instalação via CLI: Garanta que mcp-instana esteja no seu PATH
Para instalação de desenvolvimento:
- command: Atualize o caminho do uv para corresponder à instalação do uv no seu sistema (por exemplo, /path/to/your/uv/bin/uv ou /usr/local/bin/uv)
- --directory: Atualize com o caminho absoluto para o diretório do seu projeto mcp-instana
INSTANA_BASE_URL: A URL da sua instância do Instana
INSTANA_API_TOKEN: Seu token de API do Instana

Passo 2: Gerencie o Servidor no VS Code

Abra .vscode/mcp.json — você verá os controles de gerenciamento do servidor na parte superior
Clique em Start ao lado de Instana MCP Server para iniciar o servidor
O status de execução junto com o número de ferramentas indica que o servidor está em execução

Passo 3: Teste a Integração

Mude para o Modo Agente no GitHub Copilot e recarregue as ferramentas. Aqui está um exemplo de resposta do GitHub Copilot:

GitHub Copilot Response

Mistral AI

O Mistral AI suporta integração MCP exclusivamente por meio do modo Streamable HTTP.

Passo 1: Inicie o Servidor MCP no Modo Streamable HTTP

Inicie o servidor MCP no modo Streamable HTTP fornecendo suas credenciais do Instana. Execute o seguinte comando:

uv run src/core/server.py --transport streamable-http \
  --api-token "your_instana_api_token" \
  --base-url "https://your-instana-instance.instana.io" \
  --port 8080

Passo 2: Configure o Encaminhamento de Porta com o Ngrok

Configure o encaminhamento de porta para expor seu servidor local. Siga a documentação de configuração do Ngrok para instruções detalhadas.

Passo 3: Configure o Mistral AI

Navegue até a guia Inteligência na barra lateral esquerda e selecione Conectores
Clique em Adicionar Conector
Crie um conector personalizado inserindo um nome para o conector e a URL do servidor MCP encaminhada pelo Ngrok
Inicie uma nova sessão de chat e verifique se as ferramentas MCP estão ativadas. Você pode visualizar a resposta aqui

Conectando a Vários Servidores MCP do Instana

Você pode configurar seu cliente MCP para conectar a várias instâncias. Abaixo está uma configuração de exemplo:

{
  "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 direcionar um servidor específico, garanta que:

O servidor esteja configurado com o nome de ambiente apropriado na configuração MCP (por exemplo, Instana MCP Server1)
O prompt mencione explicitamente o nome do servidor/ambiente. A solicitação será então roteada para o servidor configurado correspondente. Se nenhum servidor/ambiente for explicitamente mencionado no prompt, o MCP usa o primeiro servidor definido na configuração como servidor padrão.

Observação: Se o servidor solicitado estiver inativo ou inacessível, o MCP se comporta conforme o esperado e encaminha a falha da API. O usuário receberá o erro correspondente retornado pela API, indicando que o servidor está indisponível. O MCP depende da disponibilidade da API subjacente e não realiza failover automático.

Recursos Suportados

Ferramentas Disponíveis

Ferramenta	Categoria	Descrição
`manage_applications`	Aplicação e Infraestrutura	Ferramenta unificada para gerenciar métricas de aplicações, configurações de alertas, configurações e catálogo
`manage_websites`	Monitoramento de Websites	Roteador inteligente unificado para operações de análise, catálogo, configuração e configuração avançada de websites
`manage_custom_dashboards`	Dashboards Personalizados	Ferramenta unificada para gerenciar operações CRUD de dashboards personalizados
`manage_infrastructure`	Infraestrutura	Roteador inteligente unificado para análise de infraestrutura, catálogo (`get_plugin_schema`) e operações de recursos de snapshot
`manage_automation`	Automação	Roteador inteligente unificado para automação: navegar pelo catálogo de ações e visualizar histórico de execução
`manage_events`	Eventos	Roteador inteligente unificado para monitoramento de eventos: obter evento por ID, obter eventos por IDs, eventos do Kubernetes, eventos de monitoramento de agentes e todos os eventos
`manage_slo`	Gerenciamento de SLO	Roteador inteligente unificado para configurações de SLO, relatórios, alertas e janelas de correção com tratamento inteligente de fuso horário
`manage_releases`	Gerenciamento de Releases	Roteador inteligente unificado para rastreamento de releases: listar releases com paginação e filtragem por nome, obter detalhes de release, criar/atualizar/excluir releases com suporte a fuso horário
`manage_maintenance_windows`	Janelas de Manutenção	Roteador inteligente unificado para gerenciamento do ciclo de vida de janelas de manutenção: criar, modificar, fechar e listar janelas de manutenção com suporte a modelos e integração com ServiceNow
`manage_mobile_apps`	Monitoramento de Aplicativos Móveis	Roteador inteligente unificado para monitoramento de aplicativos móveis: analisar beacons, métricas de desempenho, session replay, configuração e gerenciamento de alertas
`manage_synthetics`	Monitoramento Sintético	Roteador inteligente unificado para monitoramento sintético: catálogo, métricas, configurações (somente leitura) e resultados de reprodução de testes

👉 Para documentação detalhada de ferramentas, capacidades e referência técnica, consulte Ferramentas e Exemplos

Filtragem de Ferramentas

O servidor MCP suporta carregamento seletivo de ferramentas para otimizar o desempenho e reduzir o uso de recursos. Você pode habilitar apenas as categorias de ferramentas necessárias para seu caso de uso específico.

Categorias de Ferramentas Disponíveis

router: Gerenciamento unificado de aplicações e infraestrutura
- manage_instana_resources: Ferramenta única para métricas de aplicações, configurações de alertas, configurações e catálogo
- Suporta perspectivas de aplicações, endpoints, serviços e serviços manuais
- Gerencia configurações de alertas específicas de aplicações e globais
- Fornece acesso ao catálogo de tags de aplicações e catálogo de métricas
dashboard: Gerenciamento de dashboards personalizados
- manage_custom_dashboards: Operações CRUD para dashboards personalizados
- Suporta criação, recuperação, atualização e exclusão de dashboards
- Gerencia usuários compartilháveis e tokens de API para dashboards
infra: Ferramentas de gerenciamento de infraestrutura
- manage_infrastructure: Roteador inteligente unificado para análise de infraestrutura, catálogo e operações de recursos de snapshot
- get_plugin_schema combina get_metrics + get_tag_catalog em uma única chamada de API
- Suporta dinamicamente todos os tipos de entidade disponíveis em sua instalação da Instana (carregados automaticamente do catálogo de API)
- Inclui JVM, Kubernetes, Docker, hosts, bancos de dados, filas de mensagens e quaisquer tipos de entidade personalizados ou recém-adicionados
- Agregação flexível de métricas, filtragem, agrupamento e consultas por intervalo de tempo
automation: Ferramentas de ações de automação
- manage_automation: Roteador inteligente unificado para catálogo de automação e histórico de execução
- Catálogo de Ações: navegar por ações, obter detalhes, pesquisar por nome/descrição, filtrar por aplicação ou ID de snapshot
- Histórico de Ações: listar instâncias de execução com filtragem, obter detalhes de execução
events: Ferramentas de monitoramento de eventos
- Eventos: eventos Kubernetes, monitoramento de agentes e rastreamento de eventos do sistema
website: Ferramentas de monitoramento de sites
- Métricas de Sites: medição de desempenho para sites
- Catálogo de Sites: metadados e definições de sites
- Análise de Sites: análise de desempenho de sites
- Configuração de Sites: gerenciamento de configuração de sites
slo: Gerenciamento de Objetivo de Nível de Serviço (SLO)
- manage_slo: Roteador inteligente unificado para operações abrangentes de SLO
- Gerenciamento de Configuração: Criar, ler, atualizar, excluir configurações de SLO com suporte para indicadores baseados em tempo e em eventos
- Geração de Relatórios: Gerar relatórios detalhados de SLO com valores de SLI, orçamentos de erro, taxas de consumo e gráficos de séries temporais
- Configuração de Alertas: Gerenciar configurações de alertas de SLO para monitoramento de orçamento de erro e rastreamento de taxa de consumo
- Janelas de Correção: Criar e gerenciar janelas de manutenção para excluir tempo de inatividade planejado dos cálculos de SLO
- Tratamento Inteligente de Fuso Horário: Obtenção automática de fuso horário para entradas de data/hora, garantindo contexto de tempo preciso
- Obtenção em Duas Etapas: Coleta interativa de parâmetros para operações complexas que exigem múltiplas entradas
releases: Rastreamento de releases e gerenciamento de implantação
- manage_releases: Roteador inteligente unificado para operações de release
- Listar Releases: Obter todos os releases com paginação eficiente (page_number, page_size) e filtragem por nome
- Detalhes do Release: Recuperar informações específicas do release por ID, incluindo aplicações, serviços e escopos
- Criar/Atualizar/Excluir: Operações CRUD completas para gerenciamento de releases
- Tratamento Inteligente de Fuso Horário: Obtenção automática de fuso horário para horários de início de release
- Paginação Eficiente: Evitar busca redundante de dados com navegação adequada baseada em páginas
- Filtragem por Nome: Correspondência de substring sem diferenciar maiúsculas/minúsculas para encontrar releases por nome
maintenance_window: Gerenciamento do ciclo de vida de janelas de manutenção
- manage_maintenance_windows: Roteador inteligente unificado para operações de janelas de manutenção
- Operações de Janela: Criar, modificar, fechar e listar janelas de manutenção (ativas, agendadas, todas, expiradas)
- Operações em Lote: Criar janelas de manutenção para múltiplas aplicações simultaneamente
- Suporte a Modelos: Modelos predefinidos para cenários comuns (deployment, database_migration, infrastructure_upgrade, emergency, routine)
- Janelas Recorrentes: Suporte para janelas de manutenção recorrentes usando o formato RFC 5545 RRULE
- Integração com ServiceNow: Integração opcional com solicitações de mudança do ServiceNow
- Validação: Validação de parâmetros antes da criação da janela
- Duração Flexível: Especificar duração em minutos, horas ou dias
mobile_app: Monitoramento de aplicações móveis
- manage_mobile_apps: Roteador inteligente unificado para operações de monitoramento de aplicativos móveis
- Reprodução de Sessão: Recuperar beacons de ação de reprodução de sessão paginados por ID de aplicativo móvel e ID de sessão (resource_type="session_replay")
- Análise de Beacons: Consultar dados de beacons de aplicativos móveis com agrupamento e filtragem
- Métricas de Desempenho: Rastrear duração da sessão, taxas de falha e desempenho de solicitações HTTP
- Análise Geográfica: Analisar distribuição de usuários por país, cidade e região
- Análise de Dispositivos: Monitorar desempenho em diferentes dispositivos, plataformas e versões de SO
- Gerenciamento de Configuração: Gerenciar configurações de aplicativos móveis, geolocalização e mascaramento de IP
- Gerenciamento de Alertas: Configurar e gerenciar configurações de alertas de aplicativos móveis
synthetics: Gerenciamento de monitoramento sintético
- manage_synthetics: Roteador inteligente unificado para todas as operações de monitoramento sintético
- Catálogo: Descobrir IDs de métricas e nomes de tags válidos antes de criar consultas
- Métricas: Recuperar tempos de resposta agregados e taxas de sucesso agrupados por local ou nome de teste
- Configurações: Listar e consultar testes e locais com resolução automática de nomes; identificar PoPs de datacenter (Managed) vs. auto-hospedados (Private)
- Reprodução de Teste: Resultados brutos por execução, análises LAST_VALUE, resumos de taxa de sucesso por local e downloads de arquivos de detalhes (LOGS, HAR, screenshots)

Exemplos de Uso

Usando CLI (Instalação via PyPI)

# Enable only router (unified app/infra management) and events tools
mcp-instana --tools router,events --transport streamable-http

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

# Enable router and infrastructure analysis
mcp-instana --tools router,infra --transport streamable-http

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

# Enable dashboard and router tools
mcp-instana --tools dashboard,router --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_window,events --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

Usando Instalação de Desenvolvimento

# Enable only router (unified app/infra management) and events tools
uv run src/core/server.py --tools router,events --transport streamable-http

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

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

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

# Enable dashboard and router tools
uv run src/core/server.py --tools dashboard,router --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_window,events --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

Benefícios da Filtragem de Ferramentas

Desempenho: Tempo de inicialização e uso de memória reduzidos
Segurança: Limitar a exposição apenas às APIs necessárias
Clareza: Foco em casos de uso específicos (por exemplo, apenas monitoramento de infraestrutura)
Eficiência de Recursos: Menor uso de CPU e rede

👉 Para exemplos de uso e prompts, consulte Example Prompts

Implantação com Docker

O servidor MCP Instana pode ser implantado usando Docker para ambientes de produção. A configuração do Docker é otimizada para segurança, desempenho e uso mínimo de recursos.

Compilando a Imagem Docker

Pré-requisitos

Docker instalado e em execução
Acesso ao código-fonte do projeto

Compilar e Executar

# Build the image
docker build -t mcp-instana:latest .

# Build with a specific tag
docker build -t mcp-instana:<image_tag> .

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

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

📖 Para documentação abrangente do Docker, incluindo builds multi-arquitetura, .dockerignore, práticas recomendadas de segurança e exemplos de implantação em produção, consulte DOCKER.md.

Solução de Problemas

Problemas com Docker

O Contêiner Não Inicia

# Check container logs
docker logs <container_id>
# Common issues:
# 1. Port already in use
# 2. Invalid container image
# 3. Missing dependencies
# Credentials are passed via HTTP headers from the MCP client

Problemas de Conexão

# Test container connectivity (expects 406 from a bare GET — means server is up)
curl http://localhost:8080/mcp
# Check port mapping
docker port <container_id>

Problemas de Desempenho

# Check container resource usage
docker stats <container_id>
# Monitor container health
docker inspect <container_id> | grep -A 10 Health

Problemas Gerais

GitHub Copilot
- Se você encontrar problemas com o GitHub Copilot, tente iniciar/parar/reiniciar o servidor no arquivo mcp.json e mantenha apenas um servidor em execução por vez.
Problemas de Certificado
- Se você encontrar problemas de certificado, como [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
  - Verifique se você consegue acessar o endpoint da API do Instana usando curl ou wget com verificação SSL.
    - Se isso funcionar, seu ambiente Python pode não conseguir verificar o certificado e pode não ter acesso aos mesmos certificados que seu shell ou sistema. Garanta que seu ambiente Python use os certificados do sistema (macOS). Você pode fazer isso instalando certificados no Python: /Applications/Python\ 3.13/Install\ Certificates.command
  - Se você não conseguir acessar o endpoint com verificação SSL, tente sem ela. Se funcionar, verifique os certificados CA do seu sistema e garanta que estejam atualizados.