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.
Three audiences:
- 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
- Non-coding agents that need programmatic access to MCP tools from TypeScript — remote, persistent, or isolated agents that don't have a shell
- 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. Binaries for all platforms are also available on the GitHub 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, session id) |
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 grade [server] |
Grade server quality against the 100-point rubric |
mcpx session |
Print Streamable HTTP session ids for all servers |
mcpx session [server2...] |
Print Streamable HTTP session id(s) for specific servers |
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) |
--mcp-version |
MCP protocol era: v1, v2, or auto (default: v1) |
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=1or--no-color— disable ANSI colors.FORCE_COLOR=1or--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"
Pre-registered OAuth client (no dynamic client registration — Slack MCP, for example).
Register http://127.0.0.1:3118/callback as a redirect URI on the Slack app first.
Omit --client-secret for a public PKCE client.
mcpx add slack --url https://mcp.slack.com/mcp --transport streamable-http \
--client-id "${SLACK_CLIENT_ID}" --client-secret "${SLACK_CLIENT_SECRET}" --callback-port 3118
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. |
| `--client-id ` | Pre-registered OAuth client id. Skips dynamic client registration. |
| `--client-secret ` | OAuth client secret for a confidential client. Requires `--client-id`. |
| `--callback-port ` | Fixed loopback port for `http://127.0.0.1:/callback`. Requires `--client-id`. |
| `--transport ` | Transport: `sse` or `streamable-http` |
| `--allowed-tools ` | Allowed tool pattern. Repeatable, or comma-separated. |
| `--disabled-tools ` | Disabled tool pattern. Repeatable, or comma-separated. |
| `--mcp-version ` | MCP protocol era for this server (`v1`, `v2`, or `auto`) |
| `-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"
},
"modern-mcp": {
"url": "https://mcp.example.com",
"mcp": "v2"
},
"slack": {
"url": "https://mcp.slack.com/mcp",
"transport": "streamable-http",
"oauth": {
"clientId": "${SLACK_CLIENT_ID}",
"clientSecret": "${SLACK_CLIENT_SECRET}",
"callbackPort": 3118
}
}
}
}
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 when the server supports dynamic client registration. Servers that do not (Slack's MCP server is one) need an oauth block with a pre-registered clientId, an optional clientSecret for confidential clients, and a callbackPort whose redirect URI http://127.0.0.1:/callback is registered on the OAuth app. 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. Set "mcp": "v1", "v2", or "auto" to choose the protocol era (see MCP versions).
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. If refresh is impossible or the server still rejects the token, the command fails immediately with a prompt to run `mcpx auth ` instead of reopening the browser. `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 in-process using Xenova/bge-small-en-v1.5 (~33MB ONNX model, downloaded on first run). No API keys needed.
Config Resolution Order
MCP_CONFIG_PATHenvironment variable-c / --configflag./servers.json(current directory)~/.mcpx/servers.json
Environment Variables
| Variable | Purpose | Default |
|---|---|---|
MCP_CONFIG_PATH |
Config directory path | ~/.mcpx/ |
MCP_DEBUG |
Enable debug output | false |
MCP_TIMEOUT |
Request timeout (seconds) | 1800 |
MCP_CONCURRENCY |
Parallel server connections | 5 |
MCP_MAX_RETRIES |
Retry attempts | 3 |
MCP_STRICT_ENV |
Error on missing ${VAR} |
true |
MCP_VERSION |
MCP protocol era (v1, v2, auto) |
v1 |
MCP versions
mcpx uses the official MCP TypeScript SDK v2 client (@modelcontextprotocol/client) and can speak both protocol eras:
| Value | Handshake | Use when |
|---|---|---|
v1 |
2025 initialize (legacy). Default. |
Existing MCP servers (2024–2025 spec) |
v2 |
Pin 2026-07-28 (server/discover). No fallback. |
Servers that require the modern protocol |
auto |
Probe for 2026-07-28, fall back to the 2025 handshake | Mixed or unknown servers |
Choose it in any of these places (most specific wins):```bash
1. Per-server config (highest priority)
mcpx add github --url https://mcp.github.com --mcp-version v2
or in servers.json: { "url": "...", "mcp": "v2" }
2. CLI flag (applies to servers without an mcp field)
mcpx --mcp-version v2 ping github
mcpx --mcp-version auto exec github search_repositories '{"query":"mcp"}'
3. Environment variable
export MCP_VERSION=v2
mcpx ping github
``````typescript
// 4. TypeScript SDK
const client = new McpxClient({ mcp: "v2" });
`mcpx info ` reports the requested `mcp` value plus the negotiated `protocolVersion` and `protocolEra`.
## Server quality checks
Grade a configured MCP server across security, protocol readiness, tool quality, and surface size:```bash
mcpx grade github
mcpx grade github --json
mcpx grade github --expect github.com --min-score 80
mcpx grade github --rubric ./my-rubric.json
mcpx grade github --no-probe
Interactive output includes a color-coded ASCII letter grade, compact overall and per-category pie charts,
progress bars, detailed rule evidence, and prioritized improvements. Use --json (or --format json) for a stable
machine-readable report with schemaVersion, score, grade, category totals, status summary, and every rule result.
The default rubric is rubric/mcp-quality.json. It is the single source of truth for
rule weights and grade bands (the default uses a US school scale: A+ ≥ 97, A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60,
F below 60); custom rubrics may change weights or disable rules, but enabled weights must total
100. Safe error-quality probes call at most three tools explicitly annotated with readOnlyHint: true; use
--no-probe to skip them.
Tool-quality checks also apply the Arcade tool patterns: verb-led tool names
(read synonyms such as fetch, retrieve, lookup, and describe count alongside get/list/search), behavior
annotations that match the name's verb, permanence warnings on destructive tools, safe boolean defaults, prerequisite
hints for ID parameters, enums instead of prose choices, documented date formats, parameter examples, bounded arrays,
cursor pagination on list tools, shallow schemas, consistent parameter names, deprecation guidance, and distinct tool
descriptions.
For HTTP servers, the report also runs MCP Debugger-style wire diagnostics: malformed JSON-RPC and protocol
headers, Origin rejection, session termination, response envelopes and content types, reserved _meta, error and
notification behavior, OAuth challenge parsing, protected-resource metadata, authorization-server discovery,
PKCE, registration, grants, token authentication methods, and synthetic invalid-token rejection. The invalid-token
probe can create an expected security-log event. --no-probe disables tool calls but not these non-mutating
protocol and authorization probes.
The checks are inspired by the ToolBench methodology,
Smithery scoring guidance,
MCP Debugger and its
example report, the
official MCP conformance suite, and the
MCP tool specification.
OAuth Flow
For HTTP MCP servers that require OAuth:```bash
Start the OAuth flow — opens browser for authorization
mcpx auth github
Check token status
mcpx auth github -s
=> github: authenticated (expires in 47m)
Force re-authentication
mcpx auth github -r
Authenticate without rebuilding the search index
mcpx auth github --no-index
The OAuth flow:
1. Discovers the server's OAuth metadata via `/.well-known/oauth-authorization-server`
2. Uses `oauth.clientId` from the server config when set, and otherwise registers a client dynamically
3. Starts a local callback server on `oauth.callbackPort`, or on a random port when that is unset
4. Opens the browser for user authorization
5. Exchanges the authorization code for tokens
6. Stores tokens in `auth.json`
7. Automatically refreshes tokens before they expire on any subsequent command
8. If a stored token is rejected and cannot be refreshed, commands fail immediately with a prompt to run `mcpx auth ` — they do not reopen the browser in a loop
Slack's MCP server (`https://mcp.slack.com/mcp`) does not support dynamic client registration. Create a Slack app, enable PKCE for a public client (or keep the client secret for a confidential client), and register `http://127.0.0.1:3118/callback` — or whichever `--callback-port` you choose — as a redirect URI. Then add the server with `--client-id` and run `mcpx auth slack`.
## Search
`mcpx search` is a single command that combines keyword matching and semantic vector search. By default, both strategies run and results are merged.```bash
# Combined search (default) — keyword hits + semantic matches, merged and ranked
mcpx search "send a message to slack"
# => slack/postMessage (0.94) Post a message to a channel
# => slack/sendDirectMessage (0.87) Send a DM to a user
# => teams/sendMessage (0.72) Send a Teams message
# Keyword only — fast glob match against tool names, descriptions, and keywords
mcpx search -k "*pull*request*"
# => github/createPullRequest
# => github/getPullRequest
# => github/mergePullRequest
# Semantic only — vector similarity against intent
mcpx search -q "review someone's code changes"
# => github/submitPullRequestReview (0.91) Submit a PR review
# => github/getPullRequest (0.85) Get PR details
# => github/listPullRequestCommits (0.78) List commits in a PR
The combined search pipeline:
- Keyword match — glob/substring against tool names, descriptions, and indexed keywords
- Semantic match — embed the query, cosine similarity against tool embeddings
- Merge & rank — combine both result sets, deduplicate, sort by score
- Return — top results with similarity scores
The index updates incrementally — only new or changed tools are re-indexed. The first run indexes everything; subsequent runs are fast.
Tasks (Async Tool Execution)
MCP servers can declare support for tasks — long-running operations that return a task handle instead of blocking until completion. When a tool supports tasks (execution.taskSupport: "optional" or "required"), mcpx automatically uses task-augmented execution.```bash
Default: wait for the task to complete, showing progress updates
mcpx exec my-server long_running_tool '{"input": "data"}'
Return immediately with a task handle (useful for scripting)
mcpx exec my-server long_running_tool '{"input": "data"}' --no-wait
=> Task created: task-abc123 (status: working)
Check task status
mcpx task get my-server task-abc123
Retrieve the result once complete
mcpx task result my-server task-abc123
List all tasks on a server
mcpx task list my-server
Cancel a running task
mcpx task cancel my-server task-abc123
For tools that don't support tasks, `exec` works exactly as before — no changes needed.
## Elicitation (Server-Requested User Input)
MCP servers can request user input mid-operation via elicitation. mcpx supports both modes:
- **Form mode**: The server sends a JSON schema describing input fields (strings, numbers, booleans, enums, multi-select). mcpx renders prompts in the terminal and validates input before returning it.
- **URL mode**: The server sends a URL for the user to visit (e.g., for authentication or payment flows). mcpx opens it in the default browser.```bash
# Interactive — prompts appear in the terminal
mcpx exec my-server deploy_tool '{"target": "staging"}'
# Server requests input: Confirm deployment
# *Confirm [y/n]: y
# Non-interactive — decline all elicitation (for scripts/CI)
mcpx exec my-server deploy_tool '{"target": "staging"}' --no-interactive
# JSON mode — elicitation requests are written to stdout as JSON,
# and responses are read from stdin (for programmatic handling)
echo '{"action":"accept","content":{"confirm":true}}' | \
mcpx exec my-server deploy_tool '{"target": "staging"}' --json
Debugging with Verbose Mode
-v shows both HTTP request/response details (like curl -v) and JSON-RPC protocol messages exchanged with the server. All debug output goes to stderr so piping to jq still works.
JSON-RPC Protocol Tracing
Verbose mode traces every JSON-RPC message at the transport layer — requests, responses, and notifications — for both stdio and HTTP servers:```bash
mcpx -v exec mock echo '{"message":"hello"}'
→ initialize (id: 0)
← initialize (id: 0) [45ms] — mock-server v1.0
→ notifications/initialized
→ tools/call (id: 1)
← tools/call (id: 1) [12ms] — ok
With `--json`, trace output is NDJSON on stderr (one JSON object per message):```bash
mcpx -v -j exec mock echo '{"message":"hello"}' 2>trace.jsonl
HTTP Traffic
For HTTP/SSE servers, verbose mode also shows raw HTTP headers and timing:```bash
mcpx -v exec arcade Gmail_WhoAmI
> POST https://api.arcade.dev/mcp/evan-coding
> authorization: Bearer eyJhbGci...
> content-type: application/json
> accept: application/json, text/event-stream
>
{
"method": "tools/call",
"params": {
"name": "Gmail_WhoAmI",
"arguments": {}
}
}
< 200 OK (142ms)
< content-type: application/json
< x-request-id: abc123
<
{ "content": [ ... ] }
Debug on stderr, clean JSON on stdout
mcpx -v exec arcade Gmail_WhoAmI | jq .
Show full auth tokens (unmasked)
mcpx -v -S exec arcade Gmail_WhoAmI
The `>` / `<` convention matches curl — `>` for request, `<` for response. The `→` / `←` arrows show JSON-RPC protocol messages with method names, IDs, round-trip timing, and result summaries.
## Session IDs
Streamable HTTP servers may issue an `mcp-session-id` after initialize. That id lives on the transport mcpx keeps after connect — it is not a config-file field. You can export it from a live connection:```bash
# Print session ids for every configured server
mcpx session
# One or more servers
mcpx session github
mcpx session github linear --json
# Also included on connect metadata
mcpx ping github --json
mcpx info github
Stdio and SSE transports (and HTTP servers that omit the header) report no session id.
From TypeScript:typescript
const sessionId = await client.getSessionId("github");
// or: (await client.getServerInfo("github")).sessionId
Input Validation
…(正文过长,页面只展示前面部分,完整内容见仓库)
