Mx
CLI + local MCP gateway to centralize MCP server configs and manage Playwright pool sessions.
Quickstart (CLI)
Prereqs:
- Bun (
bun --version)
Install + register the MCP gateway (Codex + Claude Desktop + Claude Code if present):
bun installbun run setup
Optional env:
export MX_REGISTRY_PATH=...(override registry path)export MX_SOURCE_DIR=...(central source root for registry.json + skills/)export MX_PLAYWRIGHT_POOL=...(comma list, orautoto detect Playwright MCPs, oroffto disable pooling)export MX_INTERACTIONS_DIR=...(store interactions)
Centralize your existing MCP servers (Codex + Claude Code) behind the single Mx entry:
- Dry run:
bun run centralize - Apply changes:
bun run centralize -- --apply
Remove Mx and restore direct servers:
bun run decentralize
Restart Codex / Claude Desktop after setup so they reload the configs.
Standalone binaries (optional)
bun run build:gateway:exebun run build:manager:exe
Build output lands in apps/gateway/dist/ as Mx-gateway and Mx.
What's implemented
- CLI to centralize upstream MCP servers into
~/.Mx/registry.jsonand toggle configs in Codex/Claude. - Gateway that proxies upstream tools, exposes Playwright pool helpers, and can run Codex/Claude CLIs via shell.
- Gateway also exposes an Interactions-like API backed by Claude CLI (tools, background runs, basic multimodal inputs).
- Skills validation + analysis (CLI + MCP tools) and a skills sync helper from
MX_SOURCE_DIR/skills. - Commands sync support for Claude Code (
~/.claude/commands) and Codex (~/.codex/prompts) fromMX_SOURCE_DIR/commands.
Refactor notes / roadmap: docs/mx-refactor.md
Playwright scaling: docs/playwright-pool-scale.md
LLM stdio bridge (local)
The gateway exposes helpers that run the Codex and Claude CLIs via Bun's shell:
llm_codex_exec(args:args[],stdinoptional)llm_claude_exec(args:args[],stdinoptional)
Shell smoke test (runs --help/--version, and attempts a "hello world" prompt if detected):
bun run test:llm-shell- Optional overrides:
MX_CODEX_HELLO_ARGSMX_CODEX_HELLO_STDINMX_CLAUDE_HELLO_ARGSMX_CLAUDE_HELLO_STDINMX_LLM_TIMEOUT_MS(default 20000)
Interactions API (Claude-backed)
MCP tools:
interactions_create(supportsprevious_interaction_id,background, andstream)interactions_getinteractions_delete
Notes:
background: truerequiresstore: trueand returnsstatus: "in_progress"until complete.tools/tool_choiceare not supported; the Claude CLI manages tools directly.- Multimodal inputs accept content parts like
{ type: "image", data, mime_type }.
Smoke test (creates a session, follows up, background run, reads, deletes):
bun run test:interactions-claudeMX_IMAGE_TEST=1to include an optional image input check.
Playwright parallelism (local)
If you run multiple Playwright MCP servers as upstreams, the pool auto-detects them (or set an explicit list):
- Set
MX_PLAYWRIGHT_POOL=auto(default when unset) orMX_PLAYWRIGHT_POOL=playwright1,playwright2 - Call
playwright_pool_reserveorplaywright_pool_session_startto get anupstreamId - Use only that prefix for tool calls (e.g.
playwright1__browser_navigate)
Smoke test (runs 2 agents in parallel and asserts distinct slots are held concurrently):
bun run test:playwright-poolMX_PLAYWRIGHT_HEADED=1 bun run test:playwright-poolto see browsers
Note: playwright_pool_session_start creates a new tab by default. Reuse the returned sessionId,
or pass a stable sessionKey (and/or newTab: false) to avoid tab spam across restarts.
Locks auto-expire after 15 minutes of inactivity by default (TTL is refreshed on slot usage).
Operational helpers:
playwright_pool_statusshows lock/pid status and drift vs the registryplaywright_poolgenerator config.playwright_pool_session_enddefaults to keeping the tab open when asessionKeywas used (passcloseTab: trueand/orforget: trueto clean up).
Skills validation (CLI)
bun run skills validate --target bothbun run skills analyze --target codexbun run skills sync --source-dir ~/.Mx/source
Optional manifest:
~/.Mx/source/skills/manifest.jsoncontrols which top-level skill directories sync to~/.codex/skillsand~/.claude/skills.- Unlisted skills default to enabled (override via
defaultsor explicitskills.<id>entries).
Installer output:
- Gateway binary at
~/.Mx/bin/Mx-gateway - Codex config:
~/.codex/config.toml - Claude Desktop (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Code CLI:
claude mcp add-json Mx --scope user ...(if available)