# Mcpx

> Turn MCP servers into composable CLIs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lydakis-mcpx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lydakis](https://agentstack.voostack.com/s/lydakis)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lydakis](https://github.com/lydakis)
- **Source:** https://github.com/lydakis/mcpx

## Install

```sh
agentstack add mcp-lydakis-mcpx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcpx

Turn MCP servers into composable CLIs.

```bash
mcpx                        # list servers
mcpx                # list tools
mcpx   ...    # 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

```bash
brew tap lydakis/mcpx
brew install --cask mcpx
```

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

```bash
mcpx skill install
```

Add extra links as needed:

```bash
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:

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```toml
[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.

```bash
mcpx 
mcpx   --help
mcpx   ...
```

### Caching

Cache tool responses with `--cache=`, or force fresh calls with `--no-cache`:

```bash
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 `` works as a standalone command:

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

```bash
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-` by default):

```bash
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:

```bash
mcpx linear
mcpx linear  --help
mcpx linear  ...
```

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

## Reference

### Other Install Methods

**npm:**

```bash
npm install -g mcpx-go
```

**PyPI:**

```bash
pip install mcpx-go
```

**Source:**

```bash
go build ./...
./mcpx --version
```

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

### Commands

| Command | Purpose |
|---------|---------|
| `mcpx add ` | Bootstrap a server config from a source |
| `mcpx shim install ` | Install a local passthrough shim |
| `mcpx shim remove ` | Remove a shim |
| `mcpx shim list` | List installed shims |
| `mcpx completion ` | Print shell completions (bash/zsh/fish) |
| `mcpx skill install []` | Install built-in or server-specific skill |

`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 `, `mcpx   --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

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

### MCP Smoke Tests

Validate any server quickly:

```bash
mcpx                       # list tools
mcpx  --json               # machine-readable
mcpx  -v                   # full descriptions
mcpx   --help        # inspect schema
mcpx   --help --json
echo $?                            # check exit code
```

### More Examples

```bash
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:

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

## Development

### QA

```bash
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):

```bash
make perf
./scripts/perf_bench.sh           # compare against baseline
make perf-loop                              # warm CLI throughput (500 calls)
./scripts/perf_cli_loop.sh 
```

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](docs/design.md)
- [usage](docs/usage.md)
- [release](docs/release.md)
- [roadmap](docs/roadmap.md)

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lydakis](https://github.com/lydakis)
- **Source:** [lydakis/mcpx](https://github.com/lydakis/mcpx)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lydakis-mcpx
- Seller: https://agentstack.voostack.com/s/lydakis
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.