Mcpx

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:

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

# 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

# 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

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

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

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

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

{
  "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
• Source: arcadeai-labs/mcpx
• License: MIT

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