wxgov_mcp_server

PuneetUdhayan/wxgov_mcp_server

3.1

If you are the rightful owner of wxgov_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A modern Model Context Protocol (MCP) server for IBM watsonx.governance, built with FastMCP.

Tools
4
Resources
0
Prompts
0

watsonx.governance MCP Server

A modern Model Context Protocol (MCP) server for IBM watsonx.governance, built with FastMCP. Enable AI assistants to interact with watsonx.governance APIs for AI model lifecycle management and governance.

🌟 Features

Core Capabilities

  • Model Entry Management: Create and manage AI use cases
  • External Model Tracking: Register models from external platforms
  • Workspace Association: Link projects and spaces to use cases
  • Model Tracking: Track model versions across lifecycle phases
  • Configuration Resources: Query server status and environment settings

Modern Architecture

  • FastMCP Framework: Built on the latest MCP SDK with FastMCP
  • Lifespan Management: Automatic client initialization and cleanup
  • Context Injection: Type-safe dependency injection for tools
  • Structured Outputs: Pydantic models for validated responses
  • Multi-Environment Support: Seamlessly switch between dev, staging, and production
  • Automatic Authentication: Transparent IAM token management with caching
  • Progress Reporting: Real-time logging and progress updates
  • Type Safety: Full type hints and Pydantic validation throughout

📋 Prerequisites

  • Python 3.11 or higher
  • IBM Cloud API key with watsonx.governance access
  • Access to watsonx.governance catalogs

🚀 Quick Start

Installation

  1. Clone the repository:
git clone <repository-url>
cd wxgov_mcp_server
  1. Install with uv (recommended):
uv sync

Or with pip:

pip install -e .

For development:

pip install -e ".[dev]"
  1. Configure environment:
cp .env.example .env

Edit .env and set your API key:

WXGOV_ENVIRONMENT=production
WXGOV_PROD_API_KEY=your_api_key_here

Running the Server

Development Mode (with MCP Inspector):

uv run mcp dev main.py

Production Mode:

python main.py
# or
uv run main.py

Install in Claude Desktop:

uv run mcp install main.py --name "watsonx.governance"

⚙️ Configuration

Environment Variables

  • WXGOV_ENVIRONMENT: Target environment (dev, staging, production)
  • WXGOV_DEV_API_KEY: API key for development environment
  • WXGOV_STAGING_API_KEY: API key for staging environment
  • WXGOV_PROD_API_KEY: API key for production environment

Environment Configuration

The server supports multiple environments configured in config/environments.yaml:

environments:
  dev:
    api_url: "https://api.dev.dataplatform.cloud.ibm.com"
    iam_url: "https://iam.test.cloud.ibm.com"
    api_key_env_var: "WXGOV_DEV_API_KEY"
  
  production:
    api_url: "https://api.dataplatform.cloud.ibm.com"
    iam_url: "https://iam.cloud.ibm.com"
    api_key_env_var: "WXGOV_PROD_API_KEY"

🛠️ Available Tools

1. create_use_case

Create a new Model Entry (AI Use Case) in watsonx.governance.

Required Parameters:

  • name: Model entry name
  • description: Detailed description
  • catalog_id: Target catalog GUID

Optional Parameters:

  • risk_level: Risk level (low, medium, high) - default: "low"
  • status: Status (development, validation, production, retired) - default: "development"
  • owner: Owner identifier
  • tags: List of tags
  • environment: Target environment

Example:

{
  "name": "Customer Churn Prediction",
  "description": "ML model to predict customer churn risk",
  "catalog_id": "abc-123-def",
  "risk_level": "medium",
  "tags": ["churn", "classification"]
}

2. create_external_model

Create an external model (Model Stub) in watsonx.governance.

Required Parameters:

  • name: Model name
  • description: Model description
  • catalog_id: Target catalog GUID
  • model_type: Type of model (e.g., "classification", "regression")
  • external_model_provider: Provider name (e.g., "AWS SageMaker")

Optional Parameters:

  • input_type: Input data type
  • algorithm: Algorithm used
  • deployment_details: Deployment information
  • tags: List of tags
  • environment: Target environment

Example:

{
  "name": "Fraud Detection Model v1.2",
  "description": "XGBoost model for fraud detection",
  "catalog_id": "abc-123-def",
  "model_type": "classification",
  "external_model_provider": "AWS SageMaker",
  "algorithm": "xgboost",
  "deployment_details": {
    "endpoint": "https://api.example.com/predict",
    "version": "1.2.0"
  }
}

3. associate_workspaces_to_use_case

Associate workspaces (projects/spaces) with an AI use case.

Required Parameters:

  • ai_usecase_id: Model Entry Asset GUID
  • inventory_id: Catalog GUID
  • workspaces: List of workspace objects with id, type, and name

Optional Parameters:

  • phase_name: Lifecycle phase (Develop, Validate, Operate) - default: "Develop"
  • environment: Target environment

Example:

{
  "ai_usecase_id": "usecase-789",
  "inventory_id": "catalog-abc",
  "workspaces": [
    {
      "id": "proj-123",
      "type": "project",
      "name": "Development Project"
    },
    {
      "id": "space-456",
      "type": "space",
      "name": "Production Space"
    }
  ],
  "phase_name": "Develop"
}

4. track_model

Track an external model to an AI use case.

Required Parameters:

  • inventory_id: Inventory ID where model resides
  • asset_id: Model asset ID
  • usecase_inventory_id: Use case inventory ID
  • usecase_id: AI use case ID
  • version_number: Version number
  • approach_id: Approach ID

Optional Parameters:

  • phase: Lifecycle phase (Develop, Validate, Operate) - default: "Develop"
  • owner: Owner identifier
  • environment: Target environment

Example:

{
  "inventory_id": "catalog-abc",
  "asset_id": "model-123",
  "usecase_inventory_id": "catalog-abc",
  "usecase_id": "usecase-789",
  "version_number": "1.0.0",
  "approach_id": "approach-001",
  "phase": "Develop"
}

🔐 Authentication

The server uses IBM IAM for authentication:

  1. API Key: Provided via environment variable
  2. Token Exchange: API key is exchanged for a bearer token
  3. Token Caching: Tokens are cached in memory with automatic refresh
  4. Auto-Refresh: Tokens are refreshed 5 minutes before expiry

🏃 Running the Server

Claude Desktop Integration

The server is designed to work seamlessly with Claude Desktop. Use the MCP CLI to install:

uv run mcp install main.py --name "watsonx.governance" \
  -v WXGOV_ENVIRONMENT=production \
  -v WXGOV_PROD_API_KEY=your_api_key_here

Or manually add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "wxgov": {
      "command": "uv",
      "args": ["run", "/path/to/wxgov_mcp_server/main.py"],
      "env": {
        "WXGOV_ENVIRONMENT": "production",
        "WXGOV_PROD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development & Testing

With MCP Inspector (recommended for development):

uv run mcp dev main.py

Direct Execution:

python main.py
# or with uv
uv run main.py

With specific transport:

# stdio (default)
python main.py

# HTTP server
python -c "from src.server import mcp; mcp.run(transport='sse')"

📁 Project Structure

wxgov_mcp_server/
├── src/
│   ├── server.py              # FastMCP server with lifespan
│   ├── context.py             # AppContext dataclass
│   ├── config.py              # Configuration management
│   ├── models/                # Pydantic response models (NEW)
│   │   ├── __init__.py
│   │   ├── use_case.py     # UseCaseResult
│   │   ├── external_model.py  # ExternalModelResult
│   │   ├── workspace.py       # WorkspaceAssociationResult
│   │   └── tracking.py        # TrackingResult
│   ├── resources/             # Resource endpoints (NEW)
│   │   ├── __init__.py
│   │   └── config.py          # Configuration resources
│   ├── auth/
│   │   ├── iam_client.py      # IAM authentication
│   │   └── token_cache.py     # Token caching
│   ├── client/
│   │   └── wxgov_client.py    # HTTP client
│   ├── tools/
│   │   ├── use_case.py     # Use case implementation
│   │   ├── external_model.py  # External model implementation
│   │   ├── workspace.py       # Workspace association implementation
│   │   └── tracking.py        # Model tracking implementation
│   └── utils/
│       ├── exceptions.py      # Custom exceptions
│       └── logger.py          # Logging utilities
├── config/
│   └── environments.yaml      # Environment configurations
├── tests/                     # Test suite
├── examples/                  # Example scripts
├── main.py                    # Entry point (simplified)
├── pyproject.toml            # Project configuration
└── README.md                 # This file

🆕 What's New in v0.2.0

FastMCP Migration

  • Modernized Architecture: Migrated from low-level Server to FastMCP
  • Lifespan Management: Automatic client initialization and cleanup
  • Context Injection: Tools receive typed Context parameter automatically
  • Structured Outputs: All tools return Pydantic models with validation
  • Resource Endpoints: New config:// resources for server introspection
  • Simplified Entry Point: main.py is now just 8 lines!

Key Improvements

  • ~40% Less Code: Cleaner, more maintainable implementation
  • Type Safety: Full type hints with AppContext dataclass
  • Better Error Handling: Automatic error formatting and logging
  • Progress Reporting: Real-time updates via ctx.info() and ctx.error()
  • Modern Patterns: Follows latest MCP SDK best practices

🧪 Testing

Run tests:

pytest

With coverage:

pytest --cov=src --cov-report=html

🔍 Troubleshooting

Authentication Errors

Problem: AuthenticationError: IAM authentication failed

Solutions:

  • Verify API key is correct and has proper permissions
  • Check that the API key environment variable is set
  • Ensure you're using the correct environment (dev/staging/production)

API Errors

Problem: APIError: API Error 404: Not Found

Solutions:

  • Verify catalog_id, asset_id, or other IDs are correct
  • Check that resources exist in the target environment
  • Ensure you have access to the specified resources

Configuration Errors

Problem: ConfigurationError: Environment 'xyz' not configured

Solutions:

  • Check config/environments.yaml for available environments
  • Verify WXGOV_ENVIRONMENT is set to a valid environment
  • Ensure environment configuration is complete

📚 Additional Resources

🤝 Contributing

Contributions are welcome! Please follow these steps:

  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

For issues and questions:

  • Open an issue on GitHub
  • Contact the maintainers

🔄 Version History

v0.2.0 (Current) - FastMCP Migration

  • BREAKING: Migrated to FastMCP framework
  • Added structured Pydantic outputs for all tools
  • Implemented lifespan management for client initialization
  • Added Context injection pattern for tools
  • New resource endpoints: config://environments, config://status
  • Simplified entry point and server initialization
  • Enhanced logging with progress reporting
  • Improved type safety throughout

v0.1.0

  • Initial release with low-level Server
  • Four core tools: create_use_case, create_external_model, associate_workspaces_to_use_case, track_model
  • Multi-environment support
  • Automatic authentication with token caching
  • Comprehensive error handling and logging

📚 Migration Guide (v0.1.0 → v0.2.0)

If you're upgrading from v0.1.0, here are the key changes:

For Users

  • No changes required - The tool interfaces remain the same
  • New features available: Query config:// resources for server info
  • Better responses: Tools now return structured data with validation

For Developers

  • Server initialization: Now uses FastMCP with lifespan manager
  • Tool signatures: Add ctx: Context[ServerSession, AppContext] parameter
  • Return types: Tools return Pydantic models instead of strings
  • Client access: Get clients from ctx.request_context.lifespan_context
  • Logging: Use await ctx.info(), await ctx.error() instead of logger directly

See the for complete examples.