Instana Comprehensive Wrapper

A comprehensive MCP (Model Context Protocol) wrapper for all 46+ Instana monitoring tools, designed for seamless integration with WatsonX Orchestrator Cloud.

🎯 Key Features

• Complete Coverage: All 46+ tools from official mcp-instana==0.7.1 server
• WXO Cloud Compatible: Designed to work with WatsonX Orchestrator connections
• No Hardcoded Credentials: Relies on environment variables from WXO Cloud
• Simple Pass-Through: Direct mapping to official Instana tools
• Production Ready: Clean architecture, proper error handling

📦 Installation

For WatsonX Orchestrator Cloud

# Import as toolkit
Package: instana-comprehensive-wrapper==1.0.1
Command: uvx instana-comprehensive-wrapper==1.0.1 --transport stdio
Connection: Select your Instana connection (with INSTANA_API_TOKEN and INSTANA_BASE_URL)

For Local Development

pip install instana-comprehensive-wrapper

🛠️ Available Tools (46+ Tools)

Infrastructure Monitoring (1 tool)

• analyze_infrastructure_elicitation - Two-pass infrastructure analysis for any entity type

Event Monitoring (8 tools)

• get_event - Get specific event details by ID
• get_kubernetes_info_events - Kubernetes events with analysis
• get_agent_monitoring_events - Agent monitoring events
• get_issues - Warning and issue events
• get_incidents - Critical incident events
• get_changes - Deployment and configuration changes
• get_events_by_ids - Batch event retrieval

Automation/Actions (9 tools)

• get_action_matches - Find matching actions for scenarios
• get_actions - List all available actions
• get_action_details - Get action details by ID
• get_action_types - List action types
• get_action_tags - List action tags
• submit_automation_action - Execute automation action
• get_action_instance_details - Get action run details
• list_action_instances - List action run history
• delete_action_instance - Delete action run result

Dashboard Management (1 tool)

• manage_custom_dashboards - Complete dashboard CRUD operations

Application Resources (1 tool)

• manage_instana_resources - Unified resource manager for metrics, alerts, settings, catalog

Website Monitoring (26 tools)

• get_website_beacon_groups - Grouped website metrics
• get_website_beacons - All website beacons
• get_website_catalog_metrics - Metrics catalog
• get_website_catalog_tags - Tags catalog
• get_website_tag_catalog - Tag catalog for beacon type
• get_websites - List all websites
• get_website - Get website by ID
• create_website - Create new website
• delete_website - Delete website
• rename_website - Rename website
• get_website_geo_location_configuration - Get geo-location config
• update_website_geo_location_configuration - Update geo-location config
• get_website_ip_masking_configuration - Get IP masking config
• update_website_ip_masking_configuration - Update IP masking config
• get_website_geo_mapping_rules - Get geo mapping rules
• set_website_geo_mapping_rules - Set geo mapping rules
• upload_source_map_file - Upload source map
• clear_source_map_upload_configuration - Clear source map config
• get_website_page_load - Get page load details
• get_website_beacon_metrics_v2 - Get beacon metrics (v2 API)

🚀 Usage Examples

Infrastructure Monitoring

# Query host metrics
{
  "tool": "analyze_infrastructure_elicitation",
  "arguments": {
    "selections": {
      "entity_type": "host",
      "metrics": ["cpu.used", "memory.used"],
      "aggregation": "mean",
      "filters": [{"name": "host.name", "value": "my-server"}],
      "timeRange": "6h"
    }
  }
}

Database Discovery

# List all databases on a host
{
  "tool": "analyze_infrastructure_elicitation",
  "arguments": {
    "selections": {
      "entity_type": "db2Database",
      "metrics": ["db2.database.name"],
      "aggregation": "mean",
      "filters": [{"name": "host.name", "value": "db-server"}],
      "timeRange": "1h",
      "groupBy": ["db2.database.name"]
    }
  }
}

Event Monitoring

# Get incidents from last 24 hours
{
  "tool": "get_incidents",
  "arguments": {
    "time_range": "last 24 hours",
    "max_events": 50
  }
}

Application Monitoring

# Get application metrics
{
  "tool": "manage_instana_resources",
  "arguments": {
    "resource_type": "metrics",
    "operation": "application",
    "params": {
      "tag_filter_expression": {
        "type": "TAG_FILTER",
        "name": "application.name",
        "operator": "EQUALS",
        "entity": "DESTINATION",
        "value": "my-app"
      },
      "metrics": ["calls", "latency"],
      "time_frame": {"windowSize": 3600000}
    }
  }
}

🔧 Configuration

Environment Variables

The wrapper expects these environment variables (provided by WXO Cloud connection):

INSTANA_API_TOKEN=your_api_token_here
INSTANA_BASE_URL=https://your-instance.instana.io

WatsonX Orchestrator Setup

1. Create Connection:

   • Go to WXO Cloud → Connections
   • Create new connection named "instana"
   • Add Key-Value Pairs:
     • INSTANA_API_TOKEN: Your Instana API token
     • INSTANA_BASE_URL: Your Instana instance URL

2. Import Toolkit:

   • Go to WXO Cloud → Toolkits
   • Click "Import Toolkit"
   • Package: instana-comprehensive-wrapper==1.0.1
   • Command: uvx instana-comprehensive-wrapper==1.0.1 --transport stdio
   • Connection: Select "instana"

3. Test:

   • Create or open an agent
   • Try query: "Get CPU usage for [hostname] for the last 6 hours"

🏗️ Architecture

WXO Cloud Agent
    ↓
instana-comprehensive-wrapper (reads env vars from WXO connection)
    ↓
Spawns: uvx mcp-instana==0.7.1 (with credentials)
    ↓
Official Instana MCP Server
    ↓
Instana API

Key Design Principles

1. No Hardcoded Credentials: All credentials from environment
2. Simple Pass-Through: Direct mapping to official tools
3. Minimal Transformation: Only JSON parsing for WXO compatibility
4. Error Transparency: Errors passed through from official server

📚 Documentation

Tool Categories

• Infrastructure: Host, database, container, Kubernetes monitoring
• Events: Incidents, issues, changes, Kubernetes events
• Automation: Action catalog, execution, history
• Dashboards: Custom dashboard management
• Applications: Metrics, alerts, settings, catalog
• Websites: Beacon monitoring, configuration, source maps

Common Patterns

Two-Pass Infrastructure Analysis:

1. Pass 1: Provide intent and entity to get schema
2. Pass 2: Provide selections with exact parameters

Time Ranges:

• Natural language: "last 24 hours", "last 2 days"
• Milliseconds: 3600000 (1 hour), 86400000 (1 day)
• String format: "1h", "24h", "7d"

Filtering:

{
  "filters": [
    {"name": "host.name", "value": "my-server"},
    {"name": "db2.database.name", "value": "MYDB"}
  ]
}

🔍 Troubleshooting

"Environment variables not set" Error

Cause: WXO Cloud connection not properly configured Solution:

1. Verify connection has INSTANA_API_TOKEN and INSTANA_BASE_URL
2. Ensure connection is selected when importing toolkit
3. Check connection status (should show green checkmarks)

"401 Unauthorized" Error

Cause: Invalid or expired API token Solution: Update API token in WXO Cloud connection

"Host not found" Error

Cause: Hostname doesn't match Instana records Solution: Use exact hostname from Instana (case-sensitive)

Empty Results

Cause: Time range too narrow or filters too restrictive Solution: Increase time range or broaden filters

🤝 Contributing

This wrapper is designed for the DB2 DBA team's Slack bot automation project. For issues or enhancements, please contact the team.

📄 License

MIT License

🔗 Related Projects

• Official Instana MCP: https://github.com/instana/mcp-instana
• MCP Protocol: https://modelcontextprotocol.io/
• WatsonX Orchestrator: https://www.ibm.com/docs/en/watsonx/watson-orchestrate

📊 Version History

1.0.1 (2026-04-14)

• CRITICAL FIX: Corrected tool name from analyze_infrastructure to analyze_infrastructure_elicitation
• Fixed infrastructure analysis tool to match official mcp-instana server
• All infrastructure queries now work correctly

1.0.0 (2026-04-14)

• Initial release (had critical bug with wrong tool name)
• All 46+ tools from official mcp-instana server
• WXO Cloud compatible (no hardcoded credentials)
• Simple pass-through architecture
• Comprehensive documentation

---

Built for: DB2 DBA Team Slack Bot Automation Status: Production Ready Support: Internal Team Support