mcpx

Turn MCP servers into composable CLIs.

mcpx                        # list servers
mcpx <server>               # list tools
mcpx <server> <tool> ...    # call a tool

Tool names match exactly what each server exposes. Tool-call output passes through unchanged (text or JSON), so you can pipe, redirect, or parse with jq.

Quick Start

brew tap lydakis/mcpx
brew install --cask mcpx

Install the general mcpx skill for your agent (recommended on day one):

mcpx skill install

Add extra links as needed:

mcpx skill install --claude-link
mcpx skill install --kiro-link
mcpx skill install --openclaw-link

Optionally write/update a managed mcpx guidance block in your global AGENTS file:

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."

If you already use MCP in Cursor, Claude Code, Cline, Codex, or Kiro, mcpx auto-discovers those server configs.

mcpx github search-repositories --query=mcp | jq -r '.items[:3][].full_name'

No existing configs? Point mcpx at any MCP endpoint and start calling tools immediately:

mcpx https://docs.mcp.cloudflare.com/mcp
mcpx https://docs.mcp.cloudflare.com/mcp search_cloudflare_documentation --query="durable objects alarms"

Every tool gets schema-aware --help for free:

mcpx https://docs.mcp.cloudflare.com/mcp search_cloudflare_documentation --help

Going Deeper

Adding Servers

mcpx add bootstraps config from install links, manifest URLs, direct MCP endpoints, or local manifest files:

mcpx add https://mcp.deepwiki.com/mcp
mcpx deepwiki read_wiki_structure --repoName=modelcontextprotocol/specification

Added servers persist in ~/.config/mcpx/config.toml. You can also write entries by hand:

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

Ephemeral Sources

Any source you pass directly (without mcpx add) runs ephemerally for the daemon's lifetime: no config written, nothing to clean up.

mcpx <source>
mcpx <source> <tool> --help
mcpx <source> <tool> ...

Caching

Cache tool responses with --cache=<duration>, or force fresh calls with --no-cache:

mcpx deepwiki read_wiki_structure --repoName=modelcontextprotocol/specification --cache=5m
mcpx deepwiki read_wiki_structure --repoName=modelcontextprotocol/specification --no-cache

Set per-server defaults with default_cache_ttl in config.

Command Shims

Install a local passthrough so <server> works as a standalone command:

mcpx shim install github
github search-repositories --query=mcp | jq -r '.items[:3][].full_name'

Shims land in $XDG_BIN_HOME or ~/.local/bin. Install is collision-safe: it fails if that name already resolves elsewhere in PATH.

mcpx shim install github --skill   # also generate a server skill
mcpx shim list
mcpx shim remove github

Server-Specific Skills (Optional)

When you want tighter, server-specific instructions, generate a skill file for one server (written to ~/.agents/skills/mcpx-<server> by default):

mcpx skill install github
mcpx skill install github --openclaw-link

Codex Apps

When Codex Apps are enabled and authenticated locally, mcpx exposes connected apps as regular servers:

mcpx linear
mcpx linear <tool> --help
mcpx linear <tool> ...

Auth stays with Codex. mcpx does not run OAuth flows or store third-party credentials.

Reference

Other Install Methods

npm:

npm install -g mcpx-go

PyPI:

pip install mcpx-go

Source:

go build ./...
./mcpx --version

Windows: use WSL2 and run install commands inside your Linux distro shell.

Commands

mcpx add accepts --name, --header KEY=VALUE, and --overwrite. mcpx shim install accepts --skill and --skill-strict. mcpx skill install accepts --guidance, --guidance-file, and --guidance-text (--guidance follows a single --claude-link/--kiro-link/--openclaw-link target when provided).

Output Modes

--json applies to mcpx-owned surfaces only (mcpx, mcpx <server>, mcpx <server> <tool> --help). Tool-call output passes through unmodified.

Use -v to include per-server origin metadata. Combine with --json for machine-readable output including config paths.

Exit Codes

MCP Smoke Tests

Validate any server quickly:

mcpx <server>                      # list tools
mcpx <server> --json               # machine-readable
mcpx <server> -v                   # full descriptions
mcpx <server> <tool> --help        # inspect schema
mcpx <server> <tool> --help --json
echo $?                            # check exit code

More Examples

mcpx --json
mcpx github --json
mcpx github -v
mcpx github search-repositories --help --json
mcpx add "cursor://anysphere.cursor-deeplink/mcp/install?name=postgres&config=..."
mcpx add https://mcp.deepwiki.com/mcp
mcpx https://mcp.deepwiki.com/mcp
mcpx https://mcp.deepwiki.com/mcp read_wiki_structure --repoName=modelcontextprotocol/specification
mcpx add https://mcp.devin.ai/mcp --name deepwiki --header "Authorization=Bearer \${DEEPWIKI_API_KEY}"
mcpx skill install

Manual Config

If auto-discovery finds nothing, create ~/.config/mcpx/config.toml directly. For fallback setups, include -y for npx:

[servers.browser-tools]
command = "npx"
args = ["-y", "@agentdeskai/browser-tools-mcp@1.1.0"]

Development

QA

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)

Benchmarks

Benchmarks are manual (not part of CI):

make perf
./scripts/perf_bench.sh <git-ref>          # compare against baseline
make perf-loop                              # warm CLI throughput (500 calls)
./scripts/perf_cli_loop.sh <git-ref>

For summarized comparisons: go install golang.org/x/perf/cmd/benchstat@latest

Versioning

Local builds show mcpx dev. Tagged releases show the tag (for example mcpx v0.1.0) via GoReleaser ldflags.

Release

Tag pushes matching v* trigger the release workflow. GoReleaser publishes artifacts and updates lydakis/homebrew-mcpx. Notarization uses standard Apple Developer and App Store Connect secrets.

Docs

• design
• usage
• release
• roadmap

License

MIT