Instana Proxy Wrapper for WatsonX

A transparent proxy that sits between WatsonX Orchestrator and the official mcp-instana server, fixing WatsonX's JSON stringification bug while providing access to all 46 Instana tools.

🎯 Problem Solved

WatsonX Bug: WatsonX's MCP client auto-parses JSON string parameters, breaking the official mcp-instana server which expects JSON strings.

Solution: This proxy:

1. Accepts objects from WatsonX (after auto-parsing)
2. Converts them back to JSON strings
3. Forwards to official mcp-instana server
4. Returns results to WatsonX

✨ Features

• ✅ All 46 Tools: Full access to official mcp-instana tools
• ✅ Zero Configuration: Automatically starts and manages mcp-instana server
• ✅ Transparent Proxy: No changes needed to tool calls
• ✅ WatsonX Compatible: Fixes JSON stringification bug
• ✅ Easy Installation: Single package install

📦 Installation

Prerequisites

1. Install mcp-instana (the official server):

pip install mcp-instana

2. Set environment variables:

export INSTANA_BASE_URL="https://your-tenant.instana.io"
export INSTANA_API_TOKEN="your_api_token"

Install Proxy

pip install instana-proxy-wrapper

🚀 Usage

Import to WatsonX Cloud

1. Go to Skills → Import
2. Select "MCP Server"
3. Package name: instana-proxy-wrapper
4. Version: 1.0.0
5. Click Import

Environment Variables

The proxy requires the same environment variables as mcp-instana:

INSTANA_BASE_URL=https://your-tenant.instana.io
INSTANA_API_TOKEN=your_api_token

Set these in your WatsonX Cloud environment.

Local Testing

# Set credentials
export INSTANA_BASE_URL="https://your-tenant.instana.io"
export INSTANA_API_TOKEN="your_api_token"

# Run the proxy
python -m instana_proxy_wrapper.server

🔧 How It Works

Architecture

WatsonX → Proxy Wrapper → Official mcp-instana → Instana API
          (Fixes JSON)     (46 tools)

JSON Fix Example

WatsonX sends (after auto-parsing):

{
    "payload": {
        "metrics": ["cpu.utilization"],
        "timeFrame": {"windowSize": 3600000}
    }
}

Proxy converts to:

{
    "payload": '{"metrics": ["cpu.utilization"], "timeFrame": {"windowSize": 3600000}}'
}

Official server receives: JSON string (as expected)

📋 Available Tools

All 46 tools from mcp-instana are available:

Infrastructure Tools

• analyze_infrastructure_elicitation - Two-pass infrastructure analysis
• get_action_matches - Get automation action matches
• get_actions - List automation actions
• get_action_details - Get action details
• And 42 more...

Application Tools

• manage_instana_resources - Unified resource manager
• Application metrics, alerts, configurations

Event Tools

• get_event - Get specific event
• get_issues - Get issue events
• get_incidents - Get incident events
• get_changes - Get change events
• get_kubernetes_info_events - Get K8s events

Dashboard Tools

• manage_custom_dashboards - CRUD operations
• get_custom_dashboards - List dashboards
• get_custom_dashboard - Get specific dashboard

Website Monitoring Tools

• get_websites - List websites
• get_website - Get specific website
• get_website_beacons - Get website beacons
• And more...

🧪 Testing

Test Infrastructure Query

# Query DB2 databases
{
    "entity_type": "db2Database",
    "metrics": ["db2.name"],
    "aggregation": "sum",
    "filters": [
        {
            "name": "host.name",
            "value": "your-hostname"
        }
    ],
    "group_by": ["db2.name"],
    "time_range": "7d"
}

Test Two-Pass Analysis

Pass 1 - Get schema:

{
    "intent": "maximum heap size of JVM on host galactica1",
    "entity": "jvm"
}

Pass 2 - Get results:

{
    "selections": {
        "entity_type": "jvmRuntimePlatform",
        "metrics": ["jvm.heap.maxSize"],
        "aggregation": "max",
        "filters": [{"name": "host.name", "value": "galactica1"}]
    }
}

🐛 Troubleshooting

Issue: Proxy won't start

Error: "Missing required environment variables"

Solution:

export INSTANA_BASE_URL="https://your-tenant.instana.io"
export INSTANA_API_TOKEN="your_api_token"

Issue: Tools not working

Error: Tool calls fail

Solution: Ensure mcp-instana is installed:

pip install mcp-instana

Issue: Import fails in WatsonX

Error: "Package not found"

Solution: Wait 5-10 minutes for PyPI CDN propagation

📊 Comparison

Feature	instana-proxy-wrapper	instana-watsonx-wrapper
Tools	46 (all from mcp-instana)	11 (custom subset)
Metric Discovery	✅ Yes	❌ No
Two-Pass Analysis	✅ Yes	❌ No
Complexity	Low (transparent proxy)	Medium (custom implementation)
Maintenance	Low (follows mcp-instana)	High (manual updates)
Use Case	Full Instana access	Simple queries only

🎯 When to Use

Use Proxy Wrapper When:

• ✅ Need all 46 Instana tools
• ✅ Need metric discovery
• ✅ Need two-pass infrastructure analysis
• ✅ Want automatic updates with mcp-instana
• ✅ Need complex queries

Use Direct Wrapper When:

• ✅ Only need 11 basic tools
• ✅ Know exact metrics to query
• ✅ Want simpler implementation
• ✅ Don't need advanced features

📚 Documentation

• Official mcp-instana Documentation
• WatsonX Orchestrator Documentation
• MCP Protocol Specification

🤝 Contributing

This is a simple proxy wrapper. For tool improvements, contribute to the official mcp-instana project.

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Official mcp-instana server by Instana team
• Model Context Protocol by Anthropic
• WatsonX Orchestrator by IBM

---

Made with Bob - Your AI Software Engineer