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_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_keyin 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 IDfilter_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 credentialsexpected_env_vars: accepted environment variable nameshint: actionable setup instruction
Typical setup flow:
- Configure provider key in your MCP server process environment.
- Restart the MCP server process if your client does not support hot env reload.
- Call
switch_model. - 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_epochincreases.
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:
- Code follows PEP 8 and passes
ruff check - Type hints pass
mypy --strict - Tests are included for new features
- Documentation is updated
ai-mcp-model-switcher - Where MCP meets ai-lib. 🤖🔀
Metadata
Release files for ai-mcp-model-switcher 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_mcp_model_switcher-0.2.0.tar.gz | 41.1 kB | Without provenance | Details for ai_mcp_model_switcher-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_mcp_model_switcher-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for ai_mcp_model_switcher-0.2.0-py3-none-any.whl |
Total release size: 70.6 kB
Release files / ai_mcp_model_switcher-0.2.0.tar.gz
| Download URL | ai_mcp_model_switcher-0.2.0.tar.gz |
|---|---|
| Size | 41.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b430be3a89371d06168474068fbe93bd2fe6aeed0d008522c912c303fb6b3b63
|
|
BLAKE2b-256 checksum How to use checksums |
19255712d983e074eadea9e6d8b41ac569bfa90bfa350fa480aea045efc4cfbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / ai_mcp_model_switcher-0.2.0-py3-none-any.whl
| Download URL | ai_mcp_model_switcher-0.2.0-py3-none-any.whl |
|---|---|
| Size | 29.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a121edd7fb5ede446163194bd97e37d8e0b781e9e53c25870522b240666b8268
|
|
BLAKE2b-256 checksum How to use checksums |
672afb924a922399cb7ced928ae1d2e52a1df8ed4a2bc365c4d817ad0bd4aae3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for ai-mcp-model-switcher 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.