# Mcpx

> A command-line interface for MCP servers. curl for MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-arcadeai-labs-mcpx`
- **Verified:** Pending review
- **Seller:** [arcadeai-labs](https://agentstack.voostack.com/s/arcadeai-labs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [arcadeai-labs](https://github.com/arcadeai-labs)
- **Source:** https://github.com/arcadeai-labs/mcpx

## Install

```sh
agentstack add mcp-arcadeai-labs-mcpx
```

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

## About

# mcpx

A command-line interface for MCP servers. **curl for MCP.**

The internet is debating CLI vs MCP like they're competitors. [They're not.](https://arcade.dev/blog/curl-for-mcp)

Three audiences:

1. **Coding agents** (Claude Code, Cursor) that prefer shelling out over maintaining persistent MCP connections — better for token management, progressive tool discovery, and sharing a single pool of MCP servers across multiple agents on one machine
2. **Non-coding agents** that need programmatic access to MCP tools from TypeScript — remote, persistent, or isolated agents that don't have a shell
3. **MCP developers** who need a fast way to discover, debug, and test their servers from the terminal

## Install

```bash
# Via bun (all platforms)
bun install -g @arcadeai/mcpx

# Via curl (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/arcadeai-labs/mcpx/main/install.sh | bash
```

```powershell
# Via PowerShell (Windows)
irm https://raw.githubusercontent.com/arcadeai-labs/mcpx/main/install.ps1 | iex
```

The curl/PowerShell installers download a pre-built binary — no runtime needed. The bun install method requires [Bun](https://bun.sh). Binaries for all platforms are also available on the [GitHub Releases](https://github.com/arcadeai-labs/mcpx/releases) page.

## Quick Start

```bash
# Add the GitHub MCP server
mcpx add github --url https://mcp.github.com

# List all servers and their tools
mcpx

# List with descriptions
mcpx -d

# Inspect a server
mcpx info github

# Inspect a specific tool
mcpx info github search_repositories

# Execute a tool (JSON args)
mcpx exec github search_repositories '{"query": "mcp server"}'

# Execute a tool with shell-style flags (anything after `--` is parsed against the tool's input schema)
mcpx exec github search_repositories -- --query "mcp server"

# Execute a tool without specifying the server (auto-resolved)
mcpx exec search_repositories '{"query": "mcp server"}'
mcpx exec search_repositories -- --query "mcp server"

# Search tools — combines keyword and semantic matching
mcpx search "post a ticket to linear"

# Search with only keyword/glob matching (fast, no embeddings)
mcpx search -k "*file*"

# Search with only semantic matching
mcpx search -q "manage pull requests"

# Limit the number of results (default: 10)
mcpx search -n 5 "manage pull requests"
```

## Commands

| Command                                | Description                                            |
| -------------------------------------- | ------------------------------------------------------ |
| `mcpx`                                 | List all configured servers and tools                  |
| `mcpx servers`                         | List configured servers (name, type, detail)           |
| `mcpx info `                   | Server overview (version, capabilities, tools, counts) |
| `mcpx info  `            | Show tool schema                                       |
| `mcpx search `                  | Search tools (keyword + semantic)                      |
| `mcpx search -k `             | Keyword/glob search only                               |
| `mcpx search -q `               | Semantic search only                                   |
| `mcpx search -n  `      | Limit number of results (default: 10)                  |
| `mcpx index`                           | Build/rebuild the search index                         |
| `mcpx index -i`                        | Show index status                                      |
| `mcpx exec   [json]`     | Validate inputs locally, then execute tool             |
| `mcpx exec  [json]`              | Execute tool (server auto-resolved if unambiguous)     |
| `mcpx exec   -- --k=v`   | Shell-flag args (typed via the tool's input schema)    |
| `mcpx exec   -f file`    | Read tool args from a JSON file                        |
| `mcpx exec `                   | List available tools for a server                      |
| `mcpx auth `                   | Authenticate with an HTTP MCP server (OAuth)           |
| `mcpx auth  -s`                | Check auth status and token TTL                        |
| `mcpx auth  -r`                | Force token refresh                                    |
| `mcpx deauth `                 | Remove stored authentication for a server              |
| `mcpx add  --command `      | Add a stdio MCP server to your config                  |
| `mcpx add [name] --url `          | Add an HTTP MCP server (name derived from URL if omitted) |
| `mcpx remove `                   | Remove an MCP server from your config                  |
| `mcpx ping`                            | Check connectivity to all configured servers           |
| `mcpx ping  [server2...]`      | Check connectivity to specific server(s)               |
| `mcpx skill install --claude`          | Install the mcpx skill for Claude Code                 |
| `mcpx skill install --cursor`          | Install the mcpx rule for Cursor                       |
| `mcpx resource`                        | List all resources across all servers                  |
| `mcpx resource `               | List resources for a server                            |
| `mcpx resource  `         | Read a specific resource                               |
| `mcpx prompt`                          | List all prompts across all servers                    |
| `mcpx prompt `                 | List prompts for a server                              |
| `mcpx prompt   [json]`   | Get a specific prompt                                  |
| `mcpx exec [server]  --no-wait`  | Execute as async task, return task handle immediately  |
| `mcpx exec [server]  --ttl ` | Set task TTL in milliseconds (default: 60000)          |
| `mcpx task list `              | List tasks on a server                                 |
| `mcpx task get  `      | Get task status                                        |
| `mcpx task result  `   | Retrieve completed task result                         |
| `mcpx task cancel  `   | Cancel a running task                                  |
| `mcpx allow `                  | Allow an agent to exec all tools on a server           |
| `mcpx allow  `       | Allow specific tools only                              |
| `mcpx allow --all`                     | Allow all mcpx exec calls                              |
| `mcpx allow --all-read`                | Allow read-only commands (search, info, list, etc.)    |
| `mcpx allow --list`                    | Show current mcpx-related permissions                  |
| `mcpx allow --cursor `         | Allow for Cursor instead of Claude Code                |
| `mcpx deny `                   | Remove permissions for a server                        |
| `mcpx deny --all`                      | Remove all mcpx-related permissions                    |
| `mcpx check-update`                    | Check for a newer version of mcpx                      |
| `mcpx upgrade`                         | Upgrade mcpx to the latest version                     |

## Options

| Flag                      | Purpose                                                  |
| ------------------------- | -------------------------------------------------------- |
| `-h, --help`              | Show help                                                |
| `-V, --version`           | Show version                                             |
| `-d, --with-descriptions` | Include tool descriptions in list output                 |
| `-c, --config `     | Specify config file location                             |
| `-v, --verbose`           | Show HTTP details and JSON-RPC protocol messages         |
| `-S, --show-secrets`      | Show full auth tokens in verbose output (unmasked)       |
| `-j, --json`              | Force JSON output (default when piped)                   |
| `-F, --format `   | Output format: `json` or `markdown`                      |
| `-N, --no-interactive`    | Decline server elicitation requests (for scripted usage) |
| `--no-color`              | Disable ANSI colors in output                            |
| `--force-color`           | Force ANSI colors even when piped                        |
| `-l, --log-level ` | Minimum server log level to display (default: `warning`) |

### Output & colors

mcpx auto-detects whether stdout/stderr are interactive and adapts:

- TTY → colored, formatted output (tables, headers, badges).
- Non-TTY / piped → JSON.

Color emission honors the standard env vars and matching flags:

- `NO_COLOR=1` or `--no-color` — disable ANSI colors.
- `FORCE_COLOR=1` or `--force-color` — enable ANSI colors even when piped.
- `--json` / `-j` — JSON output, no colors.
- `CI=true` — treated as non-interactive (spinners off).

Server log messages (`notifications/message`) are displayed on stderr with level-appropriate coloring. Valid levels (in ascending severity): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. When a server declares logging capability, mcpx sends `logging/setLevel` to request messages at the configured threshold and above.

## Managing Servers

Add and remove servers from the CLI — no manual JSON editing required.

```bash
# Add a stdio server (anything after `--` is passed to the command verbatim)
mcpx add filesystem --command npx -- -y @modelcontextprotocol/server-filesystem /tmp

# Equivalent forms: repeatable --args, or a single comma-separated --args
mcpx add filesystem --command npx --args -y --args @modelcontextprotocol/server-filesystem --args /tmp
mcpx add filesystem --command npx --args "-y,@modelcontextprotocol/server-filesystem,/tmp"

# Add an HTTP server with headers
mcpx add my-api --url https://api.example.com/mcp --header "Authorization:Bearer tok123"

# When --url is used, the name is optional — derived from the URL's last path
# segment (or hostname if there is none). The example below stores the server
# under the name "evan-coding".
mcpx add --url https://api.arcade.dev/mcp/evan-coding

# Add with tool filtering (repeatable, or comma-separated)
mcpx add github --url https://mcp.github.com --allowed-tools "search_*" --allowed-tools "get_*"

# Add a legacy SSE server (explicit transport)
mcpx add legacy-api --url https://api.example.com/sse --transport sse

# Add with environment variables (repeatable, or comma-separated)
mcpx add my-server --command node --args server.js --env API_KEY=sk-123 --env DEBUG=true

# Overwrite an existing server
mcpx add filesystem --command echo --force

# Remove a server (also cleans up auth.json)
mcpx remove filesystem

# Remove but keep stored auth credentials
mcpx remove my-api --keep-auth

# Preview what would be removed
mcpx remove my-api --dry-run
```

**`add` options:**

| Flag                       | Purpose                                                                |
| -------------------------- | ---------------------------------------------------------------------- |
| `--command `          | Command to run (stdio server)                                          |
| `--args `             | Argument for the command. Repeatable, or comma-separated. Tokens after `--` are also appended (stdio only). |
| `--env `          | Environment variable. Repeatable, or comma-separated.                  |
| `--cwd `              | Working directory for the command                                      |
| `--url `              | Server URL (HTTP server)                                               |
| `--header `     | HTTP header. Repeatable.                                               |
| `--transport `       | Transport: `sse` or `streamable-http`                                  |
| `--allowed-tools `    | Allowed tool pattern. Repeatable, or comma-separated.                  |
| `--disabled-tools `   | Disabled tool pattern. Repeatable, or comma-separated.                 |
| `-f, --force`              | Overwrite if server already exists                                     |
| `--no-auth`                | Skip automatic OAuth after adding                                      |
| `--no-index`               | Skip rebuilding the search index                                       |

**`remove` options:**

| Flag          | Purpose                                           |
| ------------- | ------------------------------------------------- |
| `--keep-auth` | Don't remove stored auth credentials              |
| `--dry-run`   | Show what would be removed without changing files |

## Configuration

Config lives in `~/.mcpx/` (or the current directory). Three files:

### `servers.json` — MCP Server Definitions

Standard MCP server config format. Supports both stdio and HTTP servers.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": { "API_KEY": "${API_KEY}" },
      "allowedTools": ["read_file", "list_directory"],
      "disabledTools": ["delete_file"]
    },
    "github": {
      "url": "https://mcp.github.com"
    },
    "internal-api": {
      "url": "https://mcp.internal.example.com",
      "headers": { "Authorization": "Bearer ${TOKEN}" }
    },
    "legacy-sse": {
      "url": "https://legacy.example.com/sse",
      "transport": "sse"
    }
  }
}
```

**Stdio servers** — `command` + `args`, spawned as child processes
**HTTP servers** — `url`, with optional static `headers` for pre-shared tokens. OAuth is auto-discovered at connection time via `.well-known/oauth-authorization-server` — no config needed. By default, mcpx tries Streamable HTTP first and automatically falls back to legacy SSE if the server doesn't support it. Set `"transport": "sse"` or `"transport": "streamable-http"` to skip auto-detection.

Environment variables are interpolated via `${VAR_NAME}` syntax. Set `MCP_STRICT_ENV=false` to warn instead of error on missing variables.

**Tool filtering:**

- `allowedTools` — glob patterns for tools to expose (whitelist)
- `disabledTools` — glob patterns for tools to hide (blacklist, takes precedence)

### `auth.json` — OAuth Token Storage (managed automatically)

Stores OAuth tokens for HTTP MCP servers. You don't edit this directly — managed automatically.

```json
{
  "github": {
    "access_token": "gho_xxxx",
    "refresh_token": "ghr_xxxx",
    "expires_at": "2026-03-03T12:00:00Z",
    "token_type": "bearer",
    "scope": "repo,read:org"
  },
  "linear": {
    "access_token": "lin_xxxx",
    "refresh_token": "lin_ref_xxxx",
    "expires_at": "2026-03-04T08:30:00Z",
    "token_type": "bearer"
  }
}
```

Tokens are automatically refreshed when expired (if a refresh token is available). Any command that connects to a server (`exec`, `info`, `search`, listing) will refresh tokens transparently. `mcpx auth  --status` shows current token state and TTL.

### `search.json` — Semantic Search Index (managed automatically)

Contains every discovered tool with metadata for semantic search. Built by `mcpx index` and kept fresh automatically — `mcpx` (the default list) and `mcpx index --status` already fetch every server's live tools, so they detect new/changed/removed tools and re-index the affected servers in the background.

```json
{
  "version": 1,
  "indexed_at": "2026-03-03T10:00:00Z",
  "embedding_model": "Xenova/bge-small-en-v1.5",
  "tools": [
    {
      "server": "linear",
      "tool": "createIssue",
      "description": "Create a new issue in Linear",
      "input_schema": { "...": "..." },
      "scenarios": ["Create a new issue in Linear", "create issue"],
      "keywords": ["create", "issue"],
      "embedding": [0.012, -0.034, "..."]
    }
  ]
}
```

Each tool gets:

- **scenarios** — the tool description plus a keyword phrase derived from the tool name
- **keywords** — terms extracted by splitting the tool name on `_`, `-`, and camelCase boundaries
- **embedding** — 384-dim vector for cosine similarity search

Scenarios and keywords are extracted heuristically from tool names and descriptions. Embeddings are generated

…

## Source & license

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

- **Author:** [arcadeai-labs](https://github.com/arcadeai-labs)
- **Source:** [arcadeai-labs/mcpx](https://github.com/arcadeai-labs/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:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"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: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-arcadeai-labs-mcpx
- Seller: https://agentstack.voostack.com/s/arcadeai-labs
- 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%.