Instana WatsonX Wrapper v2.0.0

A WatsonX-compatible MCP server wrapper for Instana monitoring with comprehensive read-only tools.

Overview

This wrapper solves the WatsonX MCP client bug that auto-parses JSON string parameters. It provides 11 essential read-only tools for monitoring infrastructure, events, dashboards, and websites.

The Problem

WatsonX's MCP client has a bug where it:

1. Auto-parses JSON strings to objects
2. Removes parameter name wrappers
3. Breaks the MCP protocol specification

This makes the official mcp-instana package incompatible with WatsonX.

The Solution

This wrapper:

• Accepts parameters as objects (what WatsonX sends)
• Calls Instana REST API directly
• Returns properly formatted results
• Provides 11 essential read-only tools

Features

✅ 11 Read-Only Tools

Infrastructure Analysis

• analyze_infrastructure - Query metrics for hosts, databases, JVMs, etc.

Event Monitoring

• get_event - Get specific event by ID
• get_issues - Get issue events
• get_incidents - Get incident events
• get_changes - Get change events
• get_kubernetes_info_events - Get Kubernetes events

Dashboard Management

• get_custom_dashboards - List all custom dashboards
• get_custom_dashboard - Get specific dashboard by ID

Website Monitoring

• get_websites - List all monitored websites
• get_website - Get specific website by ID
• get_website_beacons - Get website performance beacons

✅ WatsonX Compatible

• Works with WatsonX Orchestrator Cloud
• No JSON string parsing issues
• Simple object parameters
• Reliable and predictable

✅ Production Ready

• Direct REST API calls (no SDK dependency issues)
• Proper error handling
• Type hints throughout
• Comprehensive documentation

Installation

Option 1: From PyPI (Recommended)

pip install instana-watsonx-wrapper

Option 2: From Source

git clone <repository-url>
cd instana-watsonx-wrapper
pip install -e .

Quick Start

1. Set Environment Variables

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

2. Run the Server

python -m instana_watsonx_wrapper.server

3. Import to WatsonX

1. Go to WatsonX Orchestrator Cloud
2. Navigate to Connections → Add Connection
3. Select MCP Server
4. Configure:
   • Name: Instana Monitoring
   • Command: python -m instana_watsonx_wrapper.server
   • Environment Variables:
     • INSTANA_BASE_URL: Your Instana URL
     • INSTANA_API_TOKEN: Your API token

4. Test with Agent

Create an agent and add the Instana toolkit. Test with:

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

Tool Reference

1. analyze_infrastructure

Query infrastructure metrics from Instana.

Parameters:

• entity_type (required): Entity type (e.g., "db2Database", "host", "jvmRuntimePlatform")
• metrics (required): List of metric names
• aggregation (required): Aggregation type ("mean", "sum", "max", "min")
• filters (optional): List of filters with name/value pairs
• group_by (optional): List of tag names to group by
• time_range (optional): Time range string (e.g., "1h", "24h", "7d")
• order_by (optional): Metric name to order by
• order_direction (optional): Sort direction ("ASC" or "DESC")

Example:

{
  "entity_type": "db2Database",
  "metrics": ["databases.status", "databases.connectionsCount"],
  "aggregation": "mean",
  "filters": [{"name": "host.name", "value": "server1"}],
  "group_by": ["db2.name"],
  "time_range": "7d"
}

2. get_event

Get a specific event by ID.

Parameters:

• event_id (required): Event ID

Example:

{
  "event_id": "abc123"
}

3. get_issues

Get issue events from Instana.

Parameters:

• from_time (optional): Start timestamp in milliseconds
• to_time (optional): End timestamp in milliseconds
• time_range (optional): Natural language time range (e.g., "1h", "24h", "7d")
• max_events (optional): Maximum events to return (default: 50)

Example:

{
  "time_range": "24h",
  "max_events": 100
}

4. get_incidents

Get incident events from Instana.

Parameters: Same as get_issues

5. get_changes

Get change events from Instana.

Parameters: Same as get_issues

6. get_kubernetes_info_events

Get Kubernetes info events from Instana.

Parameters: Same as get_issues

7. get_custom_dashboards

Get all custom dashboards.

Parameters: None

8. get_custom_dashboard

Get a specific custom dashboard by ID.

Parameters:

• dashboard_id (required): Dashboard ID

Example:

{
  "dashboard_id": "dashboard123"
}

9. get_websites

Get all monitored websites.

Parameters: None

10. get_website

Get a specific website by ID.

Parameters:

• website_id (required): Website ID

Example:

{
  "website_id": "website123"
}

11. get_website_beacons

Get website performance beacons.

Parameters:

• website_name (optional): Website name to filter by
• beacon_type (optional): Beacon type (default: "PAGELOAD")
• time_range (optional): Time range string (default: "1h")

Example:

{
  "website_name": "my-app",
  "beacon_type": "PAGELOAD",
  "time_range": "24h"
}

Common Use Cases

Monitor Database Health

"Show me the status and connection count for all databases on server X over the last 7 days"

Agent will use:

{
  "entity_type": "db2Database",
  "metrics": ["databases.status", "databases.connectionsCount"],
  "aggregation": "mean",
  "filters": [{"name": "host.name", "value": "server-x"}],
  "group_by": ["db2.name"],
  "time_range": "7d"
}

Check Recent Incidents

"Show me all incidents from the last 24 hours"

Agent will use:

{
  "time_range": "24h"
}

Monitor Website Performance

"Show me page load beacons for my-app website in the last hour"

Agent will use:

{
  "website_name": "my-app",
  "beacon_type": "PAGELOAD",
  "time_range": "1h"
}

Comparison with Official Package

Aspect	Official mcp-instana	This Wrapper
WatsonX	❌ Broken (parameter bug)	✅ Works
Tools	46+ tools	11 essential read tools
Complexity	High (SDK dependencies)	Low (direct REST API)
Maintenance	Complex	Simple
Use Case	All operations	Read-only monitoring
Dependencies	instana-python-sdk	requests only

Troubleshooting

Connection Issues

Problem: "Missing required environment variables"

Solution: Ensure both environment variables are set:

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

API Errors

Problem: "401 Unauthorized"

Solution: Verify your API token has the correct permissions in Instana.

Time Range Issues

Problem: No data returned

Solution: Try different time ranges:

• Use "7d" for databases (they update less frequently)
• Use "1h" for real-time metrics
• Use "24h" for events

Development

Running Tests

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

# Run tests
pytest

Building Package

# Install build tools
pip install build twine

# Build package
python -m build

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

Architecture

WatsonX Agent
    ↓
    ↓ (sends object parameters)
    ↓
Instana WatsonX Wrapper
    ↓
    ↓ (converts to REST API calls)
    ↓
Instana REST API
    ↓
    ↓ (returns JSON)
    ↓
WatsonX Agent (receives formatted results)

Version History

v2.0.0 (Current)

• Added 10 new read-only tools
• Infrastructure analysis
• Event monitoring (issues, incidents, changes, Kubernetes)
• Dashboard management
• Website monitoring
• Direct REST API calls (no SDK dependency)

v1.0.1

• Fixed tool name bug
• Single tool: analyze_infrastructure_elicitation

v1.0.0

• Initial release
• Single tool with wrong name

License

MIT License

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the tool reference
3. Test with the official Instana API documentation
4. Submit bug reports with detailed error messages

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

Acknowledgments

• Built to work around WatsonX MCP client limitations
• Uses Instana REST API directly for reliability
• Designed for production DB2 DBA monitoring workflows