Instana Wrapper MCP Server

A Model Context Protocol (MCP) server that wraps the Instana MCP toolkit with simplified, WatsonX-compatible interfaces. This wrapper solves parameter stringification issues and provides user-friendly tool interfaces for infrastructure monitoring, application performance, and event management.

Version 1.1.0 - Phase 1 Expansion

Tool Coverage: 13 tools (28.3% of 46 total Instana tools)

What's New in v1.1.0

• ✨ 8 new tools added (Phase 1 expansion)
• 🎯 Flexible infrastructure monitoring for any entity type
• 🔍 Event management with batch retrieval and detailed analysis
• 📊 Dashboard management with full CRUD operations
• 🌐 Website monitoring with beacon and metrics support
• ☸️ Kubernetes events with automatic problem detection

Features

Infrastructure Monitoring

• get_infrastructure_metrics: Query any entity type (hosts, databases, containers, K8s nodes)

  • Multi-metric queries (up to 10 metrics)
  • Flexible filtering by any tag
  • Optional grouping for discovery
  • Time range support (1h, 24h, 7d, etc.)

• get_host_metrics: Simplified host monitoring (CPU, memory, disk)

• get_application_metrics: Application performance (calls, latency, errors)

Event Management

• get_incidents: Critical incidents and alerts
• get_issues: Warnings and issues
• get_changes: Deployment and configuration changes
• get_event_details: Detailed event information by ID
• get_events_by_ids: Batch event retrieval
• get_kubernetes_events: K8s events with analysis
• get_agent_monitoring_events: Agent health monitoring

Dashboard Management

• manage_dashboards: Full CRUD operations
  • get_all: List all dashboards
  • get: Get specific dashboard
  • create: Create new dashboard
  • update: Update existing dashboard
  • delete: Remove dashboard

Website Monitoring

• get_website_beacons: Retrieve website beacons
• get_website_metrics: Grouped website metrics (page load, errors)

Installation

From PyPI

pip install instana-wrapper-mcp-server

From Source

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

Configuration

Hardcoded Credentials (Demo Mode)

The wrapper includes hardcoded Instana credentials for quick demos:

• API Token: ixAVRRLLQSS1P2W1cDSA7A
• Base URL: https://cp4ba-dbainternal.instana.io

Environment Variables (Production)

For production use, set environment variables:

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

Usage Examples

1. Infrastructure Monitoring - DB2 Database Health

Query 8 key DB2 metrics for PDWDBT database:

{
  "entity_type": "db2Database",
  "metrics": "[\"databases.connectionsCount\", \"databases.queries\", \"databases.commits\", \"databases.rollbacks\", \"vmonlockstats.deadlocks\", \"vmonlockstats.activeLockWaits\", \"databases.rowsRead\", \"databases.rowsReturned\"]",
  "filters": "[{\"name\": \"host.name\", \"value\": \"t3992-dev1-db-node01-par01-dev\"}, {\"name\": \"db2.name\", \"value\": \"PDWDBT\"}]",
  "aggregation": "mean",
  "time_range": "1h"
}

Result:

• Connections: 3.5
• Queries: 386.8/sec
• Commits: 103.5/sec
• Rollbacks: 0.0
• Deadlocks: 0.0 ✅
• Lock Waits: 0.0 ✅
• Rows Read: 1,088,000/sec
• Rows Returned: 1,088,000/sec

2. Database Discovery

List all databases on a host:

{
  "entity_type": "db2Database",
  "metrics": "[\"databases.connectionsCount\"]",
  "filters": "[{\"name\": \"host.name\", \"value\": \"t3992-dev1-db-node01-par01-dev\"}]",
  "group_by": "[\"db2.name\"]",
  "time_range": "24h"
}

Result: 16 databases discovered (PDWDBT, PDWDBT2, ..., PDWDBT16)

3. Host Resource Monitoring

Check CPU, memory, and disk:

{
  "hostname": "t3992-dev1-db-node01-par01-dev",
  "metrics": "[\"cpu.used\", \"memory.used\", \"memory.available\", \"disk.used\", \"disk.available\"]",
  "time_range": "1h"
}

Result:

• CPU: 93.3% ⚠️ (High)
• Memory: 88.7% ⚠️ (High)
• Available Memory: 3.8 GB

4. Application Performance

Get top endpoints for an application:

{
  "application_name": "t2916-dev1-cpe-sso",
  "metrics": "[{\"metric\": \"calls\", \"aggregation\": \"SUM\"}, {\"metric\": \"latency\", \"aggregation\": \"MEAN\"}]",
  "time_range": "1h"
}

5. Event Management

Get incident details:

{
  "event_id": "abc123xyz"
}

Get multiple events:

{
  "event_ids": "event1,event2,event3"
}

Get Kubernetes events:

{
  "time_range": "last 24 hours",
  "max_events": 50
}

6. Dashboard Management

List all dashboards:

{
  "operation": "get_all"
}

Get specific dashboard:

{
  "operation": "get",
  "dashboard_id": "dashboard-123"
}

Create dashboard:

{
  "operation": "create",
  "dashboard_config": "{\"title\": \"My Dashboard\", \"widgets\": []}"
}

7. Website Monitoring

Get website beacons:

{
  "website_name": "robot-shop",
  "beacon_type": "PAGELOAD",
  "time_range": "1h"
}

Get website metrics:

{
  "website_name": "robot-shop",
  "metrics": "[\"beaconCount\", \"pageLoadTime\"]",
  "group_by": "beacon.page.name",
  "time_range": "1h"
}

Tool Reference

Infrastructure Monitoring Tools

get_infrastructure_metrics

Most flexible tool - Query any entity type with multiple metrics and filters.

Parameters:

• entity_type (required): Entity type (e.g., "host", "db2Database", "dockerContainer")
• metrics (required): JSON array of metric names
• filters (required): JSON array of filter objects with name/value
• aggregation (optional): "mean", "max", "min", "sum" (default: "mean")
• time_range (optional): "1h", "24h", "7d" (default: "1h")
• group_by (optional): JSON array of tag names for grouping

Use Cases:

• DB2 health monitoring (8 metrics)
• Database discovery (groupBy db2.name)
• Container monitoring
• Kubernetes node monitoring

get_host_metrics

Simplified host monitoring - Quick CPU, memory, disk checks.

Parameters:

• hostname (required): Hostname or IP
• metrics (required): JSON array of metrics
• time_range (optional): Time range (default: "1h")

get_application_metrics

Application performance - Calls, latency, errors.

Parameters:

• application_name (required): Application name
• metrics (required): JSON array of metrics
• time_range (optional): Time range (default: "1h")

Event Management Tools

get_incidents

Get critical incidents and alerts.

Parameters:

• query (optional): Filter query
• time_range (optional): Time range (default: "24h")
• max_results (optional): Max results (default: 50)

get_issues

Get warnings and issues.

Parameters: Same as get_incidents

get_changes

Get deployment and configuration changes.

Parameters: Same as get_incidents

get_event_details

Get detailed information about a specific event.

Parameters:

• event_id (required): Event ID

get_events_by_ids

Get multiple events in a single request.

Parameters:

• event_ids (required): Comma-separated IDs or JSON array

get_kubernetes_events

Get Kubernetes info events with analysis.

Parameters:

• time_range (optional): Natural language (default: "last 24 hours")
• max_events (optional): Max events (default: 50)

get_agent_monitoring_events

Get agent monitoring events.

Parameters:

• query (optional): Query string
• time_range (optional): Natural language (default: "last 24 hours")
• max_events (optional): Max events (default: 50)

Dashboard Management Tools

manage_dashboards

Full CRUD operations for custom dashboards.

Parameters:

• operation (required): "get_all", "get", "create", "update", "delete"
• dashboard_id (optional): Required for get, update, delete
• dashboard_config (optional): Required for create, update

Website Monitoring Tools

get_website_beacons

Get website monitoring beacons.

Parameters:

• website_name (required): Website name
• beacon_type (optional): "PAGELOAD", "ERROR", "RESOURCE" (default: "PAGELOAD")
• time_range (optional): Time range (default: "1h")

get_website_metrics

Get grouped website metrics.

Parameters:

• website_name (required): Website name
• metrics (required): JSON array of metrics
• group_by (optional): Tag to group by (default: "beacon.page.name")
• time_range (optional): Time range (default: "1h")

WatsonX Integration

Import to WatsonX Orchestrator

1. Via GUI:

   • Navigate to Skills → Import
   • Select "MCP Toolkit"
   • Enter: uvx instana-wrapper-mcp-server==1.1.0 --transport stdio
   • Click Import

2. Via CLI:

   wxo toolkit import \
     --name "Instana Monitoring" \
     --command "uvx instana-wrapper-mcp-server==1.1.0 --transport stdio"
   

Agent Training Tips

1. Proactive Metric Selection: Train agent to automatically select useful metrics

   • DB2 Health: 8 metrics (connections, queries, commits, rollbacks, deadlocks, lock waits, rows)
   • Host Resources: 5 metrics (CPU, memory used/available, disk used/available)

2. Tool Selection Rules:

   • Infrastructure keywords (host, server, CPU, memory, database) → get_infrastructure_metrics
   • Application keywords (application, service, endpoint, API) → get_application_metrics

3. Multi-Metric Queries: Agent can query up to 10 metrics simultaneously

4. Natural Language Time Ranges: Support "last 24 hours", "last 2 days", etc.

Architecture

┌─────────────────────────────────────────┐
│   WatsonX Orchestrator / Bob            │
│   (Calls wrapper tools)                 │
└──────────────┬──────────────────────────┘
               │
               │ MCP Protocol
               │
┌──────────────▼──────────────────────────┐
│   Instana Wrapper MCP Server (v1.1.0)   │
│   - 13 simplified tools                 │
│   - Parameter normalization             │
│   - JSON parsing                        │
└──────────────┬──────────────────────────┘
               │
               │ MCP Protocol
               │
┌──────────────▼──────────────────────────┐
│   Original Instana MCP Server (v0.7.1)  │
│   - 46 native tools                     │
│   - Direct Instana API calls            │
└──────────────┬──────────────────────────┘
               │
               │ REST API
               │
┌──────────────▼──────────────────────────┐
│   Instana Backend                       │
│   - Metrics storage                     │
│   - Event management                    │
│   - Dashboard configuration             │
└─────────────────────────────────────────┘

Development

Building from Source

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

# Run tests
pytest

# Build package
python -m build

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

Testing Locally

# Test with Bob (MCP client)
# Add to Bob's MCP settings:
{
  "mcpServers": {
    "instana-wrapper": {
      "command": "uvx",
      "args": ["instana-wrapper-mcp-server==1.1.0", "--transport", "stdio"]
    }
  }
}

Roadmap

Phase 2 (Planned)

Add remaining 33 tools for complete 46-tool coverage:

• Action Catalog (4 tools): Automation actions, action matches, execution
• Application Resources (13 tools): Alert configs, perspectives, services, endpoints
• Custom Dashboards (5 tools): Shareable users/tokens, advanced operations
• Website Monitoring (11 tools): Configuration, source maps, IP masking, geo-location

Target: 100% tool coverage (46/46 tools)

Troubleshooting

Common Issues

1. "Unknown tool" error

   • Ensure you're using v1.1.0 or later
   • Check tool name spelling

2. "Invalid JSON" error

   • Ensure JSON strings are properly escaped
   • Use single quotes around JSON in shell commands

3. Empty results

   • Check time range (may need longer range)
   • Verify filter values (hostname, database name)
   • Ensure entity exists in Instana

4. Connection timeout

   • Verify Instana credentials
   • Check network connectivity
   • Ensure Instana instance is accessible

Contributing

Contributions welcome! Please:

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

License

MIT License - See LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: See CHANGELOG.md for version history
• Examples: See INSTANA_DB2_AGENT_TESTING_GUIDE.md

Acknowledgments

Built on top of the excellent mcp-instana toolkit.

---

Version: 1.1.0
Last Updated: 2026-04-13
Status: Phase 1 Complete (13/46 tools)