mcpx turns MCP servers into composable CLI commands so you can discover tools, inspect schemas, and call them with standard shell composition.

go build ./...

Project shortcuts:

make check   # test + vet + build
make qa-core # Go gates + core smoke/integration matrix
make qa-extended # CLI contract + wrapper packaging checks
make qa      # full QA matrix (core + extended)
make dist    # cross-platform artifacts + SHA256SUMS
RUN_DIST=1 make qa  # QA matrix + distribution artifact build

Create ~/.config/mcpx/config.toml:

[servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
default_cache_ttl = "30s"

[servers.github.tools.create_issue]
cache = false

For HTTP servers:

[servers.apify]
url = "https://mcp.apify.com"
headers = { Authorization = "Bearer ${APIFY_TOKEN}" }

mcpx                         # list servers
mcpx --json                  # list servers as JSON
mcpx <server>                # list tools (short descriptions)
mcpx <server> --json         # list tools as JSON
mcpx <server> -v             # list tools (full descriptions)
mcpx <server> <tool> --help  # show schema-aware help
mcpx <server> <tool> --help --json  # raw schema payload JSON
mcpx <server> <tool> ...     # call tool
mcpx <source>                # if <source> is not a known server, resolve and run it ephemerally
mcpx <source> <tool> ...     # call tools from an ephemeral source (daemon-lifetime only)
mcpx add <source>            # add server config from install link/manifest/endpoint URL
mcpx shim install <server>   # install a passthrough command shim for one server
mcpx shim remove <server>    # remove an installed shim
mcpx shim list               # list installed mcpx-managed shims
mcpx skill install           # install built-in mcpx skill for agents
mcpx skill install <server>  # generate/install a skill for one server

Tool names are used exactly as exposed by the server. Flag conventions can vary by tool and server, so run mcpx <server> <tool> --help before first use.

Ephemeral source mode reuses the same source parsing as mcpx add (install links, manifests, direct MCP endpoints) but does not write to config.toml.

--json is only for mcpx-owned outputs (mcpx, mcpx <server>, and mcpx <server> <tool> --help). Tool call output is not transformed.

mcpx server listing shows names by default. Add -v to include per-server origin metadata.

• mcpx -v: name<TAB>kind
• mcpx --json: ["name", ...]
• mcpx --json -v: [{ "name": "...", "origin": { "kind": "...", "path": "..." } }, ...]

Examples:

mcpx github search-repositories --query=mcp
mcpx github search-repositories '{"query":"mcp"}'
echo '{"query":"mcp"}' | mcpx github search-repositories

Generic pipeline:

url="$(mcpx <server> <search-tool> --query='topic' --maxResults=5 | jq -r '.results[0].url')"
mcpx <server> <read-tool> --inputs="[\"$url\"]" | jq '.content'

mcpx github search-repositories --query=mcp --cache=60s
mcpx github search-repositories --query=mcp --no-cache
mcpx github search-repositories --query=mcp --cache=60s -v

Bootstrap server config entries into ~/.config/mcpx/config.toml from:

• install-link URLs (for example Cursor-style .../mcp/install?name=...&config=...)
• manifest URLs (https://...)
• direct MCP endpoint URLs (https://.../mcp)
• local manifest files (.json or .toml)

mcpx add accepts common MCP config dialects in manifests:

• transport as string, object, or array
• type as a transport alias
• HTTP headers via headers or requestInit.headers
• stdio commands as either command string + args array or command array

Examples:

mcpx add "cursor://anysphere.cursor-deeplink/mcp/install?name=postgres&config=..."
mcpx add https://example.com/mcp-manifest.json
mcpx add https://mcp.deepwiki.com/mcp
mcpx add https://mcp.devin.ai/mcp --name deepwiki --header "Authorization=Bearer ${DEEPWIKI_API_KEY}"
mcpx add ./mcp-manifest.toml
mcpx add ./mcp-manifest.json --name github-enterprise
mcpx add ./mcp-manifest.json --overwrite

Notes:

• mcpx add writes only to mcpx config; it does not install runtimes/packages.
• Existing entries require explicit --overwrite.
• --header KEY=VALUE can be repeated and is applied only to URL-based servers.

Create optional convenience wrappers that forward directly to mcpx <server> ....

Examples:

mcpx shim install github
mcpx shim install github --skill
mcpx shim install github --skill --skill-strict
mcpx shim install linear --dir ~/.local/bin
mcpx shim list
mcpx shim remove github

Behavior:

• Shims are pass-through wrappers only; they do not install MCP servers or runtimes.
• Default install directory is $XDG_BIN_HOME (if set) or ~/.local/bin.
• Installs are collision-safe: mcpx shim install <server> fails if that command already resolves elsewhere in PATH.
• mcpx shim remove <server> removes only mcpx-managed shim files.
• mcpx shim install <server> --skill also installs a generated server skill after shim install succeeds.
• Add --skill-strict to fail if the generated skill cannot be installed.

Generate and install:

mcpx completion bash > ~/.local/share/bash-completion/completions/mcpx
mcpx completion zsh > "${fpath[1]}/_mcpx"
mcpx completion fish > ~/.config/fish/completions/mcpx.fish

If your shell does not pick up completions immediately, restart the shell.

Install the built-in mcpx skill:

mcpx skill install

By default this writes SKILL.md under ~/.agents/skills/mcpx.

Optional flags:

mcpx skill install --claude-link
mcpx skill install --kiro-link
mcpx skill install --openclaw-link
mcpx skill install --guidance
mcpx skill install --guidance --claude-link
mcpx skill install --guidance --kiro-link
mcpx skill install --guidance --openclaw-link
mcpx skill install --guidance --guidance-text "Prefer mcpx when MCP work benefits from CLI composition."
mcpx skill install --guidance-file /custom/AGENTS.md
mcpx skill install --data-agent-dir /custom/agents/skills --claude-dir /custom/.claude/skills
mcpx skill install --kiro-dir /custom/.kiro/skills --openclaw-dir /custom/.openclaw/skills

Generate and install a skill for one configured server:

mcpx skill install github
mcpx skill install github --openclaw-link
mcpx skill install github --data-agent-dir /custom/agents/skills --claude-dir /custom/.claude/skills

Generated server skills are installed under ~/.agents/skills/mcpx-<server> by default.

mcpx ships a root CLI man page (mcpx.1). Package installs place it in your manpath. For manual installs from release archives, copy man/man1/mcpx.1 into your local or system man directory, for example:

• $XDG_DATA_HOME/man/man1 (default: ~/.local/share/man/man1)

Example:

mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/man/man1"
cp man/man1/mcpx.1 "${XDG_DATA_HOME:-$HOME/.local/share}/man/man1/"
man mcpx

• mcpx: unknown server ...
  • Verify config.toml server names and run mcpx to list known servers.
• mcpx: invalid config ...
  • Fix transport settings (command xor url), URL format, cache TTL, or glob patterns.
• calling tool: ...
  • Use -v to get cache diagnostics and confirm server-side credentials/env vars.
• No fallback servers discovered:
  • By default, mcpx checks:
    • ~/.cursor/mcp.json
    • Claude Desktop config
    • Cline MCP settings
    • Claude Code user/local config (~/.claude.json)
    • Codex config (~/.codex/config.toml, mcp_servers.*; when [features].apps = true, mcpx adds virtual per-app servers like linear/zillow, backed by Codex connector auth from CODEX_CONNECTORS_TOKEN or ~/.codex/auth.json)
    • Claude Code project config (.mcp.json, nearest parent)
    • Kiro user config (~/.kiro/settings/mcp.json)
    • Kiro project config (.kiro/settings/mcp.json, nearest parent)
  • Check fallback files exist and expose either mcpServers (JSON sources) or mcp_servers (Codex TOML). Claude Code local scope uses projects[<path>].mcpServers.