Multi Agent Config

Multi-Agent Configuration Manager

Manage and sync portable AI coding-agent configuration across OpenAI Codex, Claude Code, and Cursor. Gemini helpers are placeholders and must not be treated as implemented support.

All scripts/... paths below are relative to the directory containing this SKILL.md, not the target project. Resolve the helper to an absolute path before running it with a target project argument.

Overview

This skill enables you to maintain consistent AI agent configurations across multiple platforms. It handles translation between different configuration formats (TOML ↔ JSON), directory structures, and platform-specific conventions.

Supported platforms:

• OpenAI Codex (config.toml, AGENTS.md, .agents/skills/)
• Claude Code (CLAUDE.md, .mcp.json, .claude/skills/)
• Cursor (AGENTS.md, .agents/skills/ or .cursor/skills/)

Skills and project rules sync across these targets. MCP sync is implemented for Codex and Claude Code; Cursor MCP and all Gemini mappings require current vendor documentation. Subagents and automatic hooks are host-specific and are not promised as portable translations.

Quick Start

Initialize a New Multi-Agent Project

python scripts/init_project.py /path/to/project

This creates:

• .agent-config/ - Shared source of truth
• .agents/skills/ - Shared Codex and Cursor skills
• .claude/skills/ - Claude Code skills
• AGENTS.md - Shared Codex and Cursor instructions
• Platform-specific config files

Sync Existing Configuration

# Sync all configurations to all platforms
python scripts/sync_config.py --to all

# Sync to specific platform
python scripts/sync_config.py --to claude-code

# Sync only MCP servers
python scripts/sync_config.py --mcp-only --to codex

Core Operations

1. Initialize Multi-Agent Project

When to use: Starting a new project that will be used with multiple AI code agents.

Process:

1. Run the initialization script
2. Edit shared configuration files
3. Sync to target platforms

Example:

# Initialize project
python scripts/init_project.py ./my-project

# Edit shared configuration
cd my-project
vim .agent-config/rules.md
vim .agent-config/mcp-servers.json

# Sync to all platforms
python scripts/sync_config.py --to all

2. Sync Configurations

When to use: After editing shared configs or when switching between agent platforms.

What gets synced:

• MCP server configurations
• Custom instructions/rules
• Skills (Agent Skills standard)
• Agents/subagents

Sync options:

# All configurations to all platforms
python scripts/sync_config.py --to all

# Specific platform
python scripts/sync_config.py --to codex
python scripts/sync_config.py --to claude-code

# Specific config type
python scripts/sync_config.py --mcp-only
python scripts/sync_config.py --rules-only
python scripts/sync_config.py --skills-only
python scripts/sync_config.py --agents-only

3. Add MCP Servers

Process:

1. Edit .agent-config/mcp-servers.json
2. Add server configuration
3. Sync to platforms

Example MCP server config:

{
  "servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {},
      "enabled": true,
      "description": "Developer documentation MCP"
    }
  }
}

4. Add Skills

Process:

1. Create skill in .agent-config/skills/
2. Follow Agent Skills standard
3. Sync to platforms

Example:

# Create skill directory
mkdir -p .agent-config/skills/my-skill

# Create SKILL.md
cat > .agent-config/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Description of when to use this skill
---

# My Skill

Instructions for using this skill.
EOF

# Sync to platforms
python scripts/sync_config.py --skills-only

5. Translate Configurations

When to use: Migrating from one platform to another or understanding config differences.

Platform reference docs:

• references/codex.md - Codex configuration format
• references/claude-code.md - Claude Code configuration
• references/cursor.md - Cursor skill and rule locations
• references/translation-mappings.md - Cross-platform mappings
• references/docker-mcp-gateway.md - Docker MCP Gateway

Manual translation example:

from scripts.translate_utils import ConfigTranslator, load_toml, save_json

# Load Codex config
codex_config = load_toml('~/.codex/config.toml')

# Translate MCP servers
translator = ConfigTranslator()
claude_mcp = translator.toml_mcp_to_json(codex_config)

# Save to Claude Code config
save_json(claude_mcp, '.mcp.json')

6. Migrate to Docker MCP Gateway (Recommended)

When to use: Want centralized MCP management with better security and isolation.

Benefits:

• ✅ Centralized configuration across all AI clients
• ✅ Secure secrets management (no API keys in config files)
• ✅ Container isolation for each MCP server
• ✅ Built-in OAuth flows
• ✅ No dependency management (npx, uvx, python)

Migration process:

# 1. Migrate existing MCP servers to Docker MCP Gateway
python scripts/sync_config.py --migrate-to-docker-mcp

# 2. Follow generated instructions in DOCKER_MCP_SETUP.md
# This will show you exactly which docker commands to run

# 3. Example commands (generated by migration):
docker mcp catalog init
docker mcp server enable context7 github filesystem
docker mcp secret create context7-key "your-api-key"
docker mcp secret create github-token "ghp_token"

# 4. Configure servers
docker mcp config write 'servers:
  filesystem:
    config:
      allowed_paths: ["/home/user/projects"]
  context7:
    env:
      CONTEXT7_API_KEY: secret://context7-key'

# 5. Test the gateway
docker mcp tools ls

Result: All your AI clients now use a single gateway instead of individual MCP servers.

Before (traditional):

# Codex config - managing individual servers
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { API_KEY = "exposed-in-config" }

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "exposed-in-config" }

After (Docker MCP Gateway):

# Codex config - single gateway
[mcp_servers.docker-gateway]
command = "docker"
args = ["mcp", "gateway", "run"]

All MCP configuration now managed through Docker MCP CLI:

docker mcp server ls              # List enabled servers
docker mcp secret ls              # List secrets (secure)
docker mcp config read            # View configuration

Workflow Examples

Team Standardization

# Initialize shared project config
python scripts/init_project.py ~/team-project

# Edit shared rules
vim ~/team-project/.agent-config/rules.md

# Sync to all platforms
cd ~/team-project
python scripts/sync_config.py --to all

Platform Migration

# Currently using Codex, want to try Claude Code
cd ~/my-codex-project

# Initialize Claude Code structure
python scripts/init_project.py . --platforms claude-code

# Copy Codex config to shared
cp AGENTS.md .agent-config/rules.md

# Sync to Claude Code
python scripts/sync_config.py --to claude-code

Docker MCP Gateway Migration (Recommended)

# Step 1: Migrate existing MCP servers to Docker MCP Gateway
cd ~/my-project
python scripts/sync_config.py --migrate-to-docker-mcp

# This generates DOCKER_MCP_SETUP.md with specific commands for your setup
# Example output:

# Step 2: Initialize Docker MCP
docker mcp catalog init

# Step 3: Enable your MCP servers
docker mcp server enable context7 github filesystem

# Step 4: Store secrets securely
docker mcp secret create context7-key "sk-..."
docker mcp secret create github-token "ghp_..."

# Step 5: Configure servers
docker mcp config write 'servers:
  context7:
    env:
      CONTEXT7_API_KEY: secret://context7-key
  github:
    env:
      GITHUB_TOKEN: secret://github-token
  filesystem:
    config:
      allowed_paths:
        - /home/user/projects'

# Step 6: Test the gateway
docker mcp tools ls
docker mcp tools call read_file '{"path": "README.md"}'

# Step 7: Your client configs are already updated!
# All AI clients now use the Docker MCP Gateway

Benefits of Docker MCP Gateway:

• All AI clients (Codex, Claude Code, Cursor) use the same MCP configuration
• API keys stored securely in Docker Desktop, not in config files
• Each MCP server runs in an isolated container
• Easy to enable/disable servers without editing configs
• OAuth flows handled automatically

Multi-Transport Docker MCP Gateway

# Option 1: stdio (default) - one gateway per client
# Each client starts its own gateway process
# No additional setup needed

# Option 2: SSE - shared gateway for all clients
# Start gateway once
docker mcp gateway run --port 8080 --transport sse

# Update client configs to use shared gateway
cat > ~/.codex/config.toml << EOF
[mcp_servers.docker-gateway]
url = "http://localhost:8080"
EOF

cat > .mcp.json << EOF
{
  "mcpServers": {
    "docker-gateway": {
      "url": "http://localhost:8080",
      "transport": "sse"
    }
  }
}
EOF

# Option 3: streaming - high-performance shared gateway
docker mcp gateway run --port 8080 --transport streaming

Reference Documentation

For detailed platform formats and translations:

• references/codex.md - OpenAI Codex configuration
• references/claude-code.md - Claude Code configuration
• references/cursor.md - Cursor configuration
• references/gemini.md - Gemini configuration (placeholder)
• references/docker-mcp-gateway.md - Docker MCP Gateway (recommended)
• references/translation-mappings.md - Cross-platform mappings