instana-wxo-wrapper 1.0.0

WatsonX Orchestrator-compatible wrapper for Instana MCP server with simplified tool interfaces

Instana WXO Wrapper

A WatsonX Orchestrator-compatible wrapper for Instana monitoring that provides simplified tool interfaces by handling the two-pass infrastructure analysis workflow internally.

Problem Solved

The official mcp-instana server uses a two-pass workflow for infrastructure queries:

1. Pass 1: Get schema with entity + intent parameters
2. Pass 2: Execute query with selections parameter

WatsonX Orchestrator cannot handle this workflow because it sees all parameters as independent options and cannot infer that they represent different workflow steps. This wrapper solves the problem by:

• Handling the two-pass workflow internally
• Exposing simple, single-purpose tools
• Providing formatted, readable results
• Working immediately in WXO without guidelines or training

Features

17 Simplified Tools

Database Tools (3):

• list_databases - List all databases on a host
• get_database_metrics - Detailed metrics for a specific database
• get_database_health - Health status with warnings

Host Tools (3):

• list_hosts - List all monitored hosts
• get_host_metrics - Detailed metrics for a specific host
• get_host_health - Health status with warnings

Event Tools (4):

• get_incidents - Critical incidents
• get_issues - Non-critical issues
• get_changes - Change events (deployments, config changes)
• get_kubernetes_events - Kubernetes events

Kubernetes Tools (3):

• list_kubernetes_pods - List all pods
• list_kubernetes_nodes - List all nodes
• get_pod_metrics - Detailed pod metrics

Service Tools (2):

• list_services - List all services
• get_service_metrics - Detailed service metrics

Application Tools (2):

• list_applications - List all applications
• get_application_metrics - Detailed application metrics

Installation

From PyPI (Recommended)

pip install instana-wxo-wrapper

From Source

git clone https://github.com/yourusername/instana-wxo-wrapper
cd instana-wxo-wrapper
pip install -e .

Configuration

Set environment variables:

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

Or create a .env file:

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

Usage

Running the Server

# Using the installed command
instana-wxo-wrapper

# Or using Python module
python -m instana_wxo_wrapper.server

Testing with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "instana-wxo": {
      "command": "instana-wxo-wrapper",
      "env": {
        "INSTANA_BASE_URL": "https://your-instance.instana.io",
        "INSTANA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Using with WatsonX Orchestrator

1. Import Toolkit:

   • Go to WXO Cloud → Toolkits
   • Click "Import Toolkit"
   • Select "MCP Server"
   • Enter command: uvx instana-wxo-wrapper
   • Add environment variables

2. Use in Agent:

   List all databases on t3992-dev1-db-node01-par01-dev
   

   The agent will automatically use the list_databases tool with the hostname parameter.

Example Queries

Database Monitoring

# List all databases on a host
List databases on t3992-dev1-db-node01-par01-dev

# Get detailed metrics for a specific database
Get metrics for database PDWDBT on t3992-dev1-db-node01-par01-dev

# Check database health
Check database health on t3992-dev1-db-node01-par01-dev

Host Monitoring

# List all hosts
List all monitored hosts

# Get host metrics
Get metrics for host t3992-dev1-db-node01-par01-dev

# Check host health
Check health of t3992-dev1-db-node01-par01-dev

Event Monitoring

# Get recent incidents
Show incidents from the last 24 hours

# Get issues for a specific host
Show issues for t3992-dev1-db-node01-par01-dev in the last hour

# Get recent changes
Show changes from the last 24 hours

Kubernetes Monitoring

# List pods in a namespace
List pods in namespace production

# Get pod metrics
Get metrics for pod my-app-pod in namespace production

# List all nodes
List all Kubernetes nodes

Tool Details

list_databases

Lists all databases on a specific host with status and connection count.

Parameters:

• hostname (required): Hostname or FQDN
• time_range (optional): Time range (default: "1h")

Example Output:

Databases on t3992-dev1-db-node01-par01-dev:

  • PDWDBT
    Status: ACTIVE
    Connections: 45
  • SAMPLE
    Status: ACTIVE
    Connections: 12

get_database_health

Gets health status of all databases on a host with warnings.

Parameters:

• hostname (required): Hostname or FQDN
• time_range (optional): Time range (default: "1h")

Example Output:

Database Health on t3992-dev1-db-node01-par01-dev:

  ✓ Healthy PDWDBT
  ⚠ Warning TESTDB

Warnings:
  • TESTDB: High log utilization (85.3%)

Architecture

Two-Pass Workflow (Internal)

The wrapper handles the Instana two-pass workflow internally:

1. Client Layer (client.py):

   • Manages Instana API authentication
   • Implements two_pass_query() method
   • Handles time range parsing
   • Constructs proper API payloads

2. Tools Layer (tools.py):

   • Implements 17 simplified tools
   • Calls client with appropriate parameters
   • Formats results for readability
   • Handles errors gracefully

3. Server Layer (server.py):

   • Registers tools with MCP
   • Routes tool calls to implementations
   • Manages server lifecycle

Why This Works in WXO

• Simple Parameters: Each tool has clear, single-purpose parameters
• No Workflow: No need to understand multi-step processes
• Formatted Output: Results are human-readable
• Error Handling: Clear error messages
• No Training Needed: Works immediately without guidelines

Comparison with Official Server

Feature	Official mcp-instana	instana-wxo-wrapper
Tools	46+ tools	17 tools
Workflow	Two-pass (manual)	Two-pass (automatic)
WXO Compatible	❌ No	✅ Yes
Claude Desktop	✅ Yes	✅ Yes
Output Format	Raw JSON	Formatted text
Use Case	Advanced queries	Common operations

Development

Setup

# Clone repository
git clone https://github.com/yourusername/instana-wxo-wrapper
cd instana-wxo-wrapper

# Install dependencies
pip install -e ".[dev]"

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=instana_wxo_wrapper

Building

# Build package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Troubleshooting

Server Won't Start

Error: INSTANA_BASE_URL and INSTANA_API_TOKEN must be set

Solution: Set environment variables:

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

No Data Returned

Error: No databases found on hostname

Possible Causes:

1. Hostname is incorrect (check FQDN)
2. No data in specified time range (try longer range like "24h")
3. Instana agent not reporting data

Solution: Verify hostname and try:

List databases on t3992-dev1-db-node01-par01-dev with time range 24h

API Errors

Error: 401 Unauthorized

Solution: Check API token is valid and has correct permissions

Error: 404 Not Found

Solution: Verify Instana base URL is correct

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• GitHub Issues: https://github.com/yourusername/instana-wxo-wrapper/issues
• Documentation: https://github.com/yourusername/instana-wxo-wrapper#readme

Acknowledgments

• Built on top of the official mcp-instana server
• Designed for WatsonX Orchestrator
• Uses the Model Context Protocol