mcpx

mcpx is a local MCP gateway that lets you install upstream MCP servers once, authorize them once, and expose them to multiple AI clients through managed gateway entries.

This is a monorepo containing:

• cli/ — The mcpx CLI and core library
• app/ — The macOS desktop app (Electron + React)

What it does

• Stores upstream servers in a central config (~/.config/mcpx/config.json)
• Stores upstream auth in one consolidated secure store so each MCP auth flow is done once and reused across all synced clients
• Runs a local MCP gateway daemon (http://127.0.0.1:<port>/mcp)
• Syncs managed gateway entries into supported clients (one per upstream):
  • Claude
  • Codex
  • Cursor
  • Cline
  • OpenCode
  • Kiro
  • VS Code
• Gives each upstream a top-level client entry (/vercel, /next-devtools, etc.) while routing through one local daemon.
• Uses local gateway-token auth for client -> gateway (x-mcpx-local-token)
• Supports keychain-backed secret references for upstream headers
• Passes upstream OAuth challenges (401/403 + WWW-Authenticate) through to compatible clients
• Proxies OAuth well-known metadata endpoints in single-upstream mode (/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server)

Install

Prerequisite: Node.js >=20

npm install -g @kwonye/mcpx@latest

Quick Start

Path A: Add servers with CLI (recommended)

mcpx add vercel https://example.com/mcp

mcpx add next-devtools npx next-devtools-mcp@latest

mcpx add and mcpx remove auto-sync by default. Run mcpx sync when you want a manual re-sync or to target specific clients.

Path C: Client-native compatibility shims

For convenience, mcpx also accepts client-native install commands and translates them to the canonical mcpx add flow:

# Claude Code
mcpx claude mcp add vercel https://example.com/mcp
mcpx claude mcp add next-devtools --env FOO=bar -- npx next-devtools-mcp@latest

# Codex
mcpx codex mcp add next-devtools --env FOO=bar -- npx next-devtools-mcp@latest

# VS Code
mcpx code --add-mcp '{"name":"vercel","url":"https://example.com/mcp"}'
mcpx code --add-mcp '{"name":"next-devtools","command":"npx","args":["next-devtools-mcp@latest"]}'

# Qwen CLI
mcpx qwen mcp add vercel https://example.com/mcp
mcpx qwen mcp add next-devtools --env FOO=bar -- python -m my_mcp_server

Unsupported client-native commands (e.g., cursor-agent, cline, kiro, opencode) will fail with guidance to use mcpx add directly.

Path B: Add servers manually in JSON config

Edit ~/.config/mcpx/config.json and add entries under servers:

{
  "servers": {
    "vercel": {
      "transport": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "secret://vercel_auth_header"
      }
    },
    "next-devtools": {
      "transport": "stdio",
      "command": "npx",
      "args": ["next-devtools-mcp@latest"],
      "env": {
        "FOO": "bar"
      },
      "cwd": "/path/to/project"
    }
  }
}

After manual edits, you must run:

mcpx sync

Manual config changes do not update client configs until mcpx sync runs.

Desktop App

The desktop app provides a visual interface for managing MCP servers:

• Menubar tray icon with quick-status popover
• Dashboard with server list, detail view, and daemon controls
• Browse tab to discover and one-click install servers from the official MCP Registry
• Tab navigation: Servers, Browse, Settings

Development

cd app
npm install
npm run dev      # Start Electron dev server
npm test         # Run unit tests
npm run e2e      # Run Playwright E2E tests

Supported Clients

• Claude
• Codex
• Cursor
• Cline
• VS Code

Claude Convention

mcpx follows Claude-style MCP server conventions by syncing per-upstream entries keyed by server name under mcpServers in Claude config. Each entry is an HTTP endpoint to the local gateway (/mcp?upstream=<name>) and includes the required local auth header.

How it works

1. Define upstream servers in central mcpx config.
2. mcpx ensures local gateway auth and daemon state.
3. mcpx sync writes managed client entries that point to the local gateway.

Advanced Usage

Auth and secrets

mcpx secret set vercel_auth_header --value "Bearer <token>"
mcpx secret ls
mcpx secret rm vercel_auth_header

mcpx auth set vercel --header Authorization --value "Bearer <token>"
mcpx auth set next-devtools --env NEXT_DEVTOOLS_TOKEN --value "<token>"
mcpx auth show
mcpx auth rm vercel --header Authorization --delete-secret
mcpx auth rotate-local-token

Daemon lifecycle

mcpx daemon start
mcpx daemon status
mcpx daemon logs
mcpx daemon stop

Targeted sync

mcpx sync
mcpx sync claude
mcpx sync --client claude --client codex

Config/data/state path overrides

• MCPX_CONFIG_HOME
• MCPX_DATA_HOME
• MCPX_STATE_HOME

Troubleshooting

mcpx doctor
mcpx status
mcpx daemon logs
mcpx sync --json

mcpx status now opens an interactive MCP inventory menu in TTY sessions:

• Shows each configured upstream MCP
• Shows which client config files currently have that MCP synced
• Lets you open a specific MCP and run actions (configure auth, re-authenticate, clear auth, reconnect, disable)

Build and test from source

# CLI
cd cli
npm install
npm run build
npm test

# Desktop app
cd app
npm install
npm run build
npm test

CI/CD Workflows

Top-level GitHub Actions workflows are split by release target:

• CLI release (.github/workflows/cli-release.yml)

  • Trigger: push to main when files in cli/** change.
  • Runs CLI install/build/test, computes the next shared release version, syncs CLI runtime version, conditionally syncs desktop version for mixed releases, tags release, publishes npm package, and creates/updates the GitHub Release body.
  • CLI creates v* tags for cli-only and mixed (cli/** + app/**) releases.

• Desktop release/build (.github/workflows/desktop-release.yml)

  • Triggers:
    • Push to main when files in app/** or cli/** change.
    • Push of tags matching v*.
    • Manual run (workflow_dispatch) with required release_tag input.
  • Uses annotated tag metadata (mcpx-release-v1) to determine whether desktop artifacts are included for a tag.
  • If signing/notarization secrets are present, it produces signed/notarized builds.
  • If signing secrets are missing, it falls back to unsigned builds (CSC_IDENTITY_AUTO_DISCOVERY=false) instead of skipping.
  • Publishing behavior:
    • main push with app/** changes and no cli/** changes: desktop workflow creates the next shared v* tag (desktop-only).
    • main push including cli/** changes: CLI workflow owns tag creation.
    • tag push (v*) with include_desktop=true: build and upload desktop assets to that GitHub Release tag.
    • tag push (v*) with include_desktop=false: skip desktop artifacts (cli-only release).
    • manual run: upload artifacts to the provided release_tag.
  • Single monotonic version stream:
    • every qualifying main push increments one shared patch version.
    • each version can include CLI, Desktop, or both, with component-scoped release notes.

Notes

• Client connectivity is HTTP-first.
• Upstreams can be HTTP or stdio.
• macOS keychain is the secure secret backend.
• In CI/headless environments, MCPX_SECRET_<name> env vars can override keychain lookups.