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 elsewhere, preview and explicitly import the servers you want mcpx to manage:

mcpx import                         # list supported source adapters
mcpx import claude                  # redacted preview
mcpx import claude filesystem       # import selected servers
mcpx import cursor --all            # import every supported Cursor server
mcpx import codex                   # Codex adapter also resolves plugins

When mcpx has no managed servers, it still reads common client configs as a bootstrap fallback. Once you manage servers, mcpx import keeps ownership and collisions explicit.

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"

For a protected HTTP server, let mcpx keep OAuth tokens in the OS credential store instead of config or shell history:

mcpx add https://example.com/mcp --name example --oauth
mcpx auth login example
mcpx auth status example
mcpx doctor example

Login prints the authorization URL for you to open in your browser. mcpx does not launch remote authorization URLs automatically.

Servers with a published OAuth Client ID Metadata Document can opt into it with --oauth-client-metadata-url https://client.example.com/mcpx.json.

Importing From MCP Clients

mcpx import supports Claude, Cline, Codex, Cursor, and Kiro through a shared source-adapter contract. A source preview is read-only and redacted. Selected imports are snapshotted into mcpx config with source, name, and source-context provenance so they can be refreshed later from the same workspace:

mcpx import claude
mcpx import claude filesystem
mcpx import claude --refresh

Existing managed names require --overwrite. --oauth enables first-class mcpx OAuth only for imported HTTP servers. Codex keyring tokens are never exported; authorize the managed copy with mcpx auth login <server>. Project-scoped manifests take precedence over user-level configuration and refresh from the workspace where they were imported.

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

Imported Codex Apps auth stays with Codex. For mcpx-managed remote servers, first-class OAuth is explicit per server and stored in the OS credential store.

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

Command	Purpose
mcpx add <source>	Bootstrap a server config from a source
mcpx import [<source> ...]	Preview, import, or refresh external client servers
mcpx auth login/status/logout <server>	Manage first-class remote OAuth
mcpx doctor [server] [--json]	Diagnose config, protocol, transport, and redacted auth
mcpx shim install <server>	Install a local passthrough shim
mcpx shim remove <server>	Remove a shim
mcpx shim list	List installed shims
mcpx completion <shell>	Print shell completions (bash/zsh/fish)
mcpx skill install [<server>]	Install built-in or server-specific skill

mcpx add accepts --name, --header KEY=VALUE, --oauth, --oauth-client-metadata-url URL, 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 import, mcpx <server>, mcpx <server> <tool> --help). Tool-call output passes through unmodified.

Use mcpx <server> --catalog for deterministic full tool descriptors, including input/output schemas and annotations. Complex JSON Schema inputs that cannot map truthfully to flags must be supplied as positional or stdin JSON.

MCP 2026-07-28 multi-round-trip calls return an input_required JSON result with exit code 1 by default. Resume with --request-state and --input-responses, or opt into TTY elicitation with --interactive.

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

Exit Codes

Code	Meaning
0	Success
1	Tool error (MCP isError)
2	Usage error
3	Internal error

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)
make conformance-core # pinned official MCP 2026-07-28 tools_call scenario

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