ai-mcp-model-switcher 0.2.0

MCP server for dynamic AI model switching in ai-lib ecosystem

MCP Model Switcher for ai-lib Ecosystem

MCP (Model Context Protocol) server that enables agents to dynamically switch AI models from the ai-lib ecosystem.

Features

• Protocol-Driven: All model configurations loaded from ai-protocol manifests (ARCH-001)
• Multi-Provider Support: Switch between OpenAI, Anthropic, Google, DeepSeek, and more
• Runtime-Agnostic: Uses ai-lib-python SDK for unified model interaction
• MCP-Compliant: Implements standard MCP tools over stdio transport
• Capability Discovery: Query available models and their capabilities

Quick Start

Installation

# Clone the repository
git clone https://github.com/yourorg/ai-mcp-model-switcher.git
cd ai-mcp-model-switcher

# Install dependencies
pip install -e .

Environment Setup

Set up your API keys:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

Recommended provider key mapping:

Provider	Environment Variable
openai	OPENAI_API_KEY
anthropic	ANTHROPIC_API_KEY
google	GOOGLE_API_KEY or GEMINI_API_KEY
deepseek	DEEPSEEK_API_KEY
cohere	COHERE_API_KEY
mistral	MISTRAL_API_KEY

Security note:

• Prefer environment variables over passing api_key in tool arguments.
• The server redacts sensitive fields in logs, but passing secrets in arguments still increases exposure risk in client traces.

Configuration

Add to your MCP client configuration (e.g., Cursor, Claude Desktop):

{
  "mcpServers": {
    "ai-model-switcher": {
      "command": "python",
      "args": ["-m", "ai_mcp_model_switcher.server"],
      "env": {
        "AI_PROTOCOL_PATH": "/path/to/ai-protocol"
      }
    }
  }
}

Usage

In your agent, call MCP tools:

# List available models
models = await mcp_client.call_tool("list_models", {})

# Switch to Claude 3.5 Sonnet
await mcp_client.call_tool(
    "switch_model",
    {"model": "anthropic/claude-3-5-sonnet"}
)

# Check current status
status = await mcp_client.call_tool("get_status", {})

Available MCP Tools

1. switch_model

Switches to a different AI model/provider.

Parameters:

• model (string, required): Model identifier (e.g., openai/gpt-4o, anthropic/claude-3-5-sonnet)
• api_key (string, optional): Explicit API key (overrides environment variable; not recommended for production)
• base_url (string, optional): Custom base URL for testing/mock

Returns:

{
  "status": "success",
  "current_provider": "anthropic",
  "current_model": "claude-3-5-sonnet",
  "capabilities": ["streaming", "tools", "vision"]
}

2. list_models

Lists all available models from registered providers.

Parameters:

• filter_provider (string, optional): Filter by provider ID
• filter_capability (string, optional): Filter by capability (streaming, tools, vision, embeddings)

Returns:

{
  "models": [
    {
      "id": "openai/gpt-4o",
      "provider": "openai",
      "capabilities": ["streaming", "tools", "vision"]
    },
    {
      "id": "anthropic/claude-3-5-sonnet",
      "provider": "anthropic",
      "capabilities": ["streaming", "tools", "vision"]
    }
  ]
}

3. get_status

Gets current model status and configuration.

Returns:

{
  "provider": "anthropic",
  "model": "claude-3-5-sonnet",
  "capabilities": ["streaming", "tools", "vision"],
  "is_configured": true,
  "connection_epoch": 3,
  "last_switched_at": "2026-03-02T09:00:00+00:00"
}

API Key Guidance and Troubleshooting

When switch_model fails due to missing credentials, the response includes:

• provider: which provider is missing credentials
• expected_env_vars: accepted environment variable names
• hint: actionable setup instruction

Typical setup flow:

1. Configure provider key in your MCP server process environment.
2. Restart the MCP server process if your client does not support hot env reload.
3. Call switch_model.
4. Verify with get_status.

Connection Coordination with Agent Runtime

This MCP server manages model client lifecycle internally. To avoid conflicts with an agent's own connection manager:

• Treat MCP switcher as the control plane for model selection.
• Let the agent side observe get_status.connection_epoch.
• Rebuild agent-side cached sessions only when connection_epoch increases.

This pattern prevents stale session reuse after model switches and supports deterministic synchronization.

Architecture

ai-mcp-model-switcher/
├── src/
│   ├── server.py           # MCP server main entry point
│   ├── tools/              # MCP tool implementations
│   │   ├── switch.py       # switch_model tool
│   │   ├── list.py         # list_models tool
│   │   └── status.py       # get_status tool
│   ├── runtime/            # Runtime abstraction layer
│   │   ├── base.py         # Base runtime interface
│   │   ├── python_runtime.py  # ai-lib-python implementation
│   │   └── loader.py       # ProtocolLoader wrapper
│   └── state.py            # State management
├── tests/                  # Test suite
└── pyproject.toml          # Project configuration

Development

Running Tests

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

# Run tests
pytest

# Run with coverage
pytest --cov=src/ai_mcp_model_switcher

Testing with Mock Server

Use ai-protocol-mock:

# Start mock server
docker-compose up -d ai-protocol-mock

# Run with mock
MOCK_HTTP_URL=http://localhost:4010 python -m ai_mcp_model_switcher.server

Code Style

# Format code
ruff format src tests

# Lint
ruff check src tests

# Type check
mypy src

Protocol-Driven Design (ARCH-001)

This server follows the ai-lib design principle:

一切逻辑皆算子，一切配置皆协议

All provider configurations are loaded from ai-protocol manifests. No provider-specific logic is hardcoded. Adding a new provider requires only a manifest file in ai-protocol.

Related Projects

• ai-protocol - Protocol specification
• ai-lib-python - Python runtime SDK
• ai-lib-rust - Rust runtime SDK
• ai-lib-ts - TypeScript runtime SDK

License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please ensure:

1. Code follows PEP 8 and passes ruff check
2. Type hints pass mypy --strict
3. Tests are included for new features
4. Documentation is updated

---

ai-mcp-model-switcher - Where MCP meets ai-lib. 🤖🔀