Content
# Codex MCP Migration Package
> Automatically fallback to frontend MCP tools when third-party backends like DeepSeek cannot provide image recognition or internet search.
## File Structure
```
codex-mcp-migration/
├── README.md ← This file
├── setup.sh ← One-click deployment script
├── mcp-servers/
│ ├── vision-server.py ← Visual MCP (Qwen-VL)
│ └── search-server.py ← Search MCP (Tavily)
└── config/
├── mcp-config.toml ← MCP server registration (append to config.toml)
└── AGENTS-rules.md ← Backend capability fallback rules (append to AGENTS.md)
```
## Migration Steps
### 0. Prerequisites
- macOS with Codex installed
- Target machine can run `python3` (system built-in)
- Prepare two API Keys:
- Qwen-VL (DashScope): Image recognition — https://dashscope.console.aliyun.com → Model Service → API-KEY Management → Create
- Tavily: Internet search — https://app.tavily.com → Sign Up → API Keys
- Both have free quotas: DashScope new users get 1 million tokens for free, Tavily offers 1000 free searches per month
### 1. Deploy MCP Server
```bash
# Copy MCP server to a unified directory
mkdir -p ~/.codex/mcp-servers
cp mcp-servers/vision-server.py ~/.codex/mcp-servers/
cp mcp-servers/search-server.py ~/.codex/mcp-servers/
# Fill in API Key → Replace placeholders
# vision-server.py: Search for YOUR_DASHSCOPE_KEY_HERE
# search-server.py: Search for YOUR_TAVILY_KEY_HERE
```
### 2. Register to Codex config.toml
Open `~/.codex/config.toml`, append the content of `config/mcp-config.toml` to the end of the file:
```toml
[mcp_servers.vision-mcp]
command = "python3"
args = ["/Users/YourUsername/.codex/mcp-servers/vision-server.py"]
startup_timeout_sec = 30
[mcp_servers.search-mcp]
command = "python3"
args = ["/Users/YourUsername/.codex/mcp-servers/search-server.py"]
startup_timeout_sec = 30
```
> **Note**: Replace `/Users/YourUsername/` with the actual username or use shell expansion symbols. Using `~` or `$HOME` is not allowed in `config.toml`, and you must write the absolute path.
### 3. Write AGENTS Fallback Rules
Append the "[Backend Capability Fallback]" rule from `config/AGENTS-rules.md` to `~/.codex/AGENTS.md` or `~/AGENTS.md`.
### 4. Verification
Restart Codex and open a new session:
1. **Visual Test**: Send an image, agent attempts backend → fails → calls `analyze_image` MCP → first-time popup authorization → returns image description.
2. **Search Test**: Ask a real-time question, agent calls `web_search` MCP → first-time popup authorization → returns search results.
### 5. Working Principle
```
User sends image/question
↓
Agent attempts backend capability (may fail / third-party API does not support)
↓
AGENTS.md rules: backend fails → MCP tools
↓
analyze_image ⋮ web_search (MCP)
↓
Qwen-VL Vision API ⋮ Tavily Search API
```
## Troubleshooting
| Phenomenon | Check |
|:-----|:----|
| MCP tool does not appear | `grep "mcp_servers" ~/.codex/config.toml` to confirm registration |
| Key error when calling | Check if API Key in server.py has been replaced |
| Agent does not call MCP tool | AGENTS.md rules are written to the correct location |
