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

O que você pode fazer com IBM Instana MCP?

Recuperar snapshots de infraestrutura — Solicite um snapshot de um host, processo ou contêiner específico usando get_infra_snapshot.
Analisar métricas de aplicação ou serviço — Solicite métricas de série temporal para chamadas, erros ou latência com get_app_metrics ou get_service_metrics.
Listar alertas e incidentes ativos — Obtenha alertas, incidentes ou alertas inteligentes globais atuais via get_alerts e get_incidents.
Inspecionar eventos do Kubernetes — Extraia eventos recentes do Kubernetes para um cluster ou namespace com get_k8s_events.
Consultar dados de monitoramento de sites — Busque métricas de desempenho de sites ou resultados de beacon através de get_website_metrics.

Documentação

Índice

Servidor MCP para IBM Instana

Servidor MCP para IBM Instana

📚 Links Rápidos

Ferramentas e Exemplos - Documentação abrangente das 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 uma interação perfeita com a plataforma de observabilidade Instana, possibilitando o acesso a 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 requisições à API do Instana e formatando as respostas em formatos estruturados e fáceis de consumir.

O servidor suporta os modos de transporte HTTP Transmissível 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 do servidor MCP do Instana
Sua consulta é enviada ao LLM juntamente 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) através 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 pelo 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 o 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 Modo HTTP Transmissível

Ao usar o modo HTTP Transmissível, 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 requisições diferentes
Suportar ambientes compartilhados onde a modificação de variáveis de ambiente é restrita
Suportar autenticação por token de API e baseada 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: 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 IU)

Cabeçalhos Necessários:

instana-base-url: URL da sua instância do Instana
instana-auth-token: Token de autenticação de sessão do backend da IU
instana-csrf-token: Token CSRF do backend da IU
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: URL da sua instância do Instana
instana-jwt-token: Token JWT da Plataforma IBM
instana-csrf-token: Token CSRF para validação da requisição

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 ambos 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 requisição
O servidor valida as credenciais com base na ordem de prioridade
Requisiçõ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 IU via WebSocket → Coordenador → Servidor MCP.

Certifique-se de 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 Transmissível e Stdio.

Opções de Comando do Servidor

Usando a CLI (Instalação pelo PyPI)

Se você instalou o mcp-instana pelo 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 serem ativadas (ex.: infra,app,events,website). Ativar uma categoria também ativará seus prompts relacionados. Por exemplo: --tools infra ativa as ferramentas de infra e todos os prompts relacionados a infra.
--list-tools: Listar todas as categorias de ferramentas disponíveis e sair
--port <port>: Porta do servidor MCP (padrão: 8080, pode ser sobrescrita com a variável de ambiente PORT)
--help: Mostrar mensagem de ajuda e sair

Iniciando no Modo HTTP Transmissível

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

Usando a CLI (Instalação pelo 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 Características do Modo HTTP Transmissível:

Usa cabeçalhos HTTP para autenticação (sem necessidade de variáveis de ambiente)
Suporta credenciais diferentes por requisiçã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 pelo 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 Características do Modo Stdio:

Usa variáveis de ambiente para autenticação (podem ser definidas via export ou flag --env)
Comunicação direta via stdin/stdout
Necessário para certas configurações de cliente 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 pelo 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 do Kubernetes, monitoramento de agentes)
website: Ferramentas e prompts de monitoramento de websites (métricas, catálogo, análise, configuração)

Verificando o Status do Servidor

Uma vez iniciado, você pode verificar se o servidor está em execução:

Para o modo HTTP Transmissível:

# 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á entrada stdin dos clientes MCP.

Problemas Comuns na Inicialização

Problemas de Certificado: Se você encontrar erros de certificado SSL, certifique-se de 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: Certifique-se de que todas as dependências estejam instaladas:

uv sync

Configuração e Uso

Bob IDE

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

Modo HTTP Transmissível

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

Passo 1: Iniciar o Servidor MCP no Modo HTTP Transmissível

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

Passo 2: Configurar o Bob

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

Ao selecionar isso, você poderá ver a opção de configurar o MCP no nível do projeto ou no nível global.

Escopos de Configuração do MCP

O Bob oferece suporte a dois níveis de configuração do MCP, permitindo que você escolha o escopo que melhor se adapta ao seu caso de uso:

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

A configuração global aplica servidores MCP a 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 projetos diferentes exigem configurações de servidor MCP diferentes ou quando você deseja compartilhar as configurações do 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 disponíveis 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 obter mais informações sobre o Bob e a configuração do MCP, visite: https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

Configuração Local:

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

{
  "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 se conectar a um servidor MCP remoto do Instana (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: Testar 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á sendo executado com sucesso.

Agora você pode executar consultas no IDE Bob:

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 o sinalizador --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 o sinalizador --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 oferece suporte aos modos HTTP Transmissível 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 HTTP Transmissível

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

Passo 1: Iniciar o Servidor MCP no Modo HTTP Transmissível

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

Passo 2: Configurar 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: Testar 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 o sinalizador --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 o sinalizador --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 seu modo de transporte preferido:

Modo HTTP Transmissível (Recomendado para 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 http transmissível 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 o sinalizador --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 oferece suporte à integração MCP por meio da configuração do VS Code. Para integração do GitHub Copilot com o VS Code, consulte este guia de configuração.

Modo HTTP Transmissível

Passo 1: Iniciar o Servidor MCP no Modo HTTP Transmissível

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

Passo 2: Configurar o VS Code

Consulte Usar servidores MCP no VS Code para obter a 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: 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: Criar a Configuração MCP do VS Code

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

Crie .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 o sinalizador --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 .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 o sinalizador --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: Certifique-se de que mcp-instana esteja no seu PATH
Para instalação de desenvolvimento:
- command: Atualize o caminho do uv para corresponder à instalação do uv do 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: URL da sua instância do Instana
INSTANA_API_TOKEN: Seu token de API do Instana

Passo 2: Gerenciar 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: Testar 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 oferece suporte à integração MCP exclusivamente por meio do modo HTTP Transmissível.

Passo 1: Iniciar o Servidor MCP no Modo HTTP Transmissível

Inicie o servidor MCP no modo HTTP Transmissível 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: Configurar o Encaminhamento de Porta com Ngrok

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

Passo 3: Configurar 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 de 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

Recursos Suportados

Ferramentas Disponíveis

Ferramenta	Categoria	Descrição
`manage_applications`	Aplicação e Infraestrutura	Ferramenta unificada para gerenciar métricas de aplicação, configurações de alerta, definições e catálogo
`manage_websites`	Monitoramento de Website	Roteador inteligente unificado para operações de análise, catálogo, configuração e configuração avançada de website
`manage_custom_dashboards`	Dashboards Personalizados	Ferramenta unificada para gerenciar operações CRUD de dashboards personalizados
`analyze_infrastructure`	Análise de Infraestrutura	Análise de infraestrutura em duas passagens com elicitação de entidade/métrica
`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 agente 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 da 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 App Móvel	Roteador inteligente unificado para monitoramento de app móvel: analisar beacons, métricas de desempenho, configuração e gerenciamento de alertas

👉 Para documentação detalhada das 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 o 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ção, configurações de alerta, definições e catálogo
- Suporta perspectivas de aplicação, endpoints, serviços e serviços manuais
- Gerencia configurações de alerta específicas da aplicação e globais
- Fornece acesso ao catálogo de tags de aplicação 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 análise de infraestrutura
- analyze_infrastructure: Análise de infraestrutura em duas passagens com elicitação de entidade/métrica
- Suporta dinamicamente todos os tipos de entidade disponíveis na sua instalação do Instana (carregados automaticamente do catálogo da 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 ID de aplicação ou snapshot
- Histórico de Ações: listar instâncias de execução com filtragem, obter detalhes da execução
events: Ferramentas de monitoramento de eventos
- Eventos: eventos do Kubernetes, monitoramento de agente e rastreamento de eventos do sistema
website: Ferramentas de monitoramento de websites
- Métricas de Website: Medição de desempenho para websites
- Catálogo de Website: Metadados e definições de websites
- Análise de Website: Análise de desempenho de websites
- Configuração de Website: Gerenciamento de configuração de websites
slo: Gerenciamento de Service Level Objective (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érie temporal
- Configuração de Alertas: Gerenciar configurações de alerta 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: Elicitação automática de fuso horário para entradas de data/hora para garantir contexto de tempo preciso
- Elicitação em Duas Passagens: Coleta interativa de parâmetros para operações complexas que exigem múltiplas entradas
releases: Rastreamento de releases e gerenciamento de implantações
- manage_releases: Roteador inteligente unificado para operações de release
- Listar Releases: Obter todas as releases com paginação eficiente (page_number, page_size) e filtragem por nome
- Detalhes da Release: Recuperar informações específicas da 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: Elicitação automática de fuso horário para horários de início da 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 distinção entre maiúsculas e 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 janela 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 (implantação, migração de banco de dados, atualização de infraestrutura, emergência, rotina)
- 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 aplicativos móveis
- manage_mobile_apps: Roteador inteligente unificado para operações de monitoramento de apps móveis
- Análise de Beacon: Consulte dados de beacon de apps móveis com agrupamento e filtragem
- Métricas de Desempenho: Acompanhe duração da sessão, taxas de falha e desempenho de requisições HTTP
- Análise Geográfica: Analise a distribuição de usuários por país, cidade e região
- Análise de Dispositivos: Monitore o desempenho em diferentes dispositivos, plataformas e versões de SO
- Gerenciamento de Configuração: Gerencie configurações de apps móveis, geolocalização e ajustes de mascaramento de IP
- Gerenciamento de Alertas: Configure e gerencie configurações de alertas para apps móveis

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: Limita a exposição apenas às APIs necessárias
Clareza: Foco em casos de uso específicos (ex.: apenas monitoramento de infraestrutura)
Eficiência de Recursos: Menor uso de CPU e rede

👉 Para exemplos de uso e prompts, veja Exemplos de Prompts

Implantação com Docker

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

Arquitetura Docker

O projeto utiliza uma estratégia de gerenciamento de dependências em dois arquivos:

pyproject.toml

Propósito: Configuração unificada para desenvolvimento e produção
Dependências: Todas as dependências essenciais com dependências opcionais de desenvolvimento
Uso: Desenvolvimento local, testes, CI/CD e builds Docker de produção
Benefícios: Fonte única de verdade para todas as dependências, manutenção simplificada

Construindo a Imagem Docker

Pré-requisitos

Docker instalado e em execução
Acesso ao código-fonte do projeto
Docker BuildKit para builds multiarquitetura (habilitado por padrão em versões recentes do Docker)

Comando de Build

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

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

#### **Run Command**
# Run the container (no credentials needed in the container)
docker run -p 8080:8080 mcp-instana

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

📖 Para documentação Docker abrangente, incluindo builds multiarquitetura, configuração com Docker Compose, melhores práticas de segurança e exemplos de implantação em produção, veja DOCKER.md.

Solução de Problemas

Problemas com Docker

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
docker exec -it <container_id> curl http://127.0.0.1:8080/health
# 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 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 encontrar problemas de certificado, como [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
  - Verifique se consegue acessar o endpoint da API do Instana usando curl ou wget com verificação SSL.
    - Se 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. Certifique-se de que seu ambiente Python use certificados do sistema (macOS). Você pode fazer isso instalando certificados no Python: //Applications/Python\ 3.13/Install\ Certificates.command
  - Se 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.