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 e analisar alertas do Instana — Pergunte sobre alertas atuais para um aplicativo ou serviço específico usando get_alerts.
Consultar métricas e topologia da infraestrutura — Obtenha métricas de CPU, memória ou disco e explore relacionamentos de recursos com get_metrics e get_topology.
Investigar eventos do Kubernetes — Exiba eventos recentes do cluster, avisos ou alterações de status do agente por meio de get_events.
Monitorar desempenho de sites — Obtenha métricas específicas de sites, analise carregamentos de página ou revise a configuração do site por meio de get_website_metrics e get_website_configuration.
Descobrir aplicativos e serviços monitorados — Liste aplicativos, endpoints ou entradas de catálogo em sua instância do Instana usando get_applications e get_catalog.

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 serve 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 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 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 via cabeçalhos HTTP. Esta 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 via PyPI)

Se você instalou o mcp-instana 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 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 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 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 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 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 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 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 suporta 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 de Usuário)

A configuração global aplica servidores MCP em todos os projetos para o 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 de Projeto (Nível de Projeto)

A configuração de 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 configurações do MCP com sua equipe via controle de versão.

Local do Arquivo:

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

Escolhendo entre Configuração Global e de Projeto:

Use a configuração global para servidores MCP que você deseja disponíveis em todos os seus projetos
Use a configuração de 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 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 habilitado. Um ponto verde indica que o servidor está em execução 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 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 em vez disso.

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 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 via 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 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 em vez disso.

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 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 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 Habilitar 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 através 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 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 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 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 .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: 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 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: URL da sua instância do Instana
INSTANA_API_TOKEN: Seu token de API do Instana

Passo 2: Gerenciar Servidor no VS Code

Abra .vscode/mcp.json - você verá os controles de gerenciamento do servidor no topo
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 suporta integração MCP exclusivamente através 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 habilitadas. 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 análise de website, catálogo, configuração e operações de configuração avançada
`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 snapshot de recursos
`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 aplicativos móveis: analisar beacons, métricas de desempenho, reprodução de sessão, 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 gerenciamento de infraestrutura
- manage_infrastructure: Roteador inteligente unificado para análise de infraestrutura, catálogo e operações de snapshot de recursos
- get_plugin_schema combina get_metrics + get_tag_catalog em uma única chamada de API
- 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 RRULE da RFC 5545
- Integração com ServiceNow: Integração opcional com requisições de mudança do ServiceNow
- Validação: Validação de parâmetros antes da criação da janela
- Duração Flexível: Especifique a 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 apps móveis
- Reprodução de Sessão: Recuperar beacons de ação de reprodução de sessão paginados por ID do app móvel e ID da sessão (resource_type="session_replay")
- Análise de Beacons: Consultar dados de beacon de app móvel com agrupamento e filtragem
- Métricas de Desempenho: Acompanhar duração da sessão, taxas de falha e desempenho de requisiçõ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 app móvel, geolocalização e mascaramento de IP
- Gerenciamento de Alertas: Configurar e gerenciar configurações de alerta de app móvel

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 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 usa uma estratégia de gerenciamento de dependências com 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 multi-arquitetura (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 multi-arquitetura, configuração do 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 certifique-se de que estão atualizados.