Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
npx -y @arcadeai/[email protected]Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
claude mcp add arcadeai-mcpx -- npx -y @arcadeai/mcpx@1.5.2Ejecútalo en una terminal.
{ "mcpServers": { "arcadeai-mcpx": { "command": "npx", "args": [ "-y", "@arcadeai/[email protected]" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
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:
A command-line interface for MCP servers. curl for MCP.
# 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.
# 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"
mcpx auto-detects whether stdout/stderr are interactive and adapts:
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.
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"
# 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:
remove options:
Config lives in ~/.mcpx/ (or the current directory). Three files:
servers.json — MCP Server DefinitionsStandard 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"
},
"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:<port>/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.
{
"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 <server> instead of reopening the browser. mcpx auth <server> --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:
_, -, and camelCase boundariesScenarios 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.
MCP_CONFIG_PATH environment variable-c / --config flag./servers.json (current directory)~/.mcpx/servers.jsonmcpx uses the official MCP TypeScript SDK v2 client (@modelcontextprotocol/client) and can speak both protocol eras:
Choose it in any of these places (most specific wins):
# 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
// 4. TypeScript SDK
const client = new McpxClient({ mcp: "v2" });
mcpx info <server> reports the requested mcp value plus the negotiated protocolVersion and protocolEra.
Grade a configured MCP server across security, protocol readiness, tool quality, and surface size:
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.
For HTTP MCP servers that require OAuth:
# 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:
/.well-known/oauth-authorization-serveroauth.clientId from the server config when set, and otherwise registers a client dynamicallyoauth.callbackPort, or on a random port when that is unsetauth.jsonmcpx auth <server> — they do not reopen the browser in a loopSlack'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.
mcpx search is a single command that combines keyword matching and semantic vector search. By default, both strategies run and results are merged.
# 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:
The index updates incrementally — only new or changed tools are re-indexed. The first run indexes everything; subsequent runs are fast.
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.
# 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.
MCP servers can request user input mid-operation via elicitation. mcpx supports both modes:
# 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
-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.
Verbose mode traces every JSON-RPC message at the transport layer — requests, responses, and notifications — for both stdio and HTTP servers:
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):
mcpx -v -j exec mock echo '{"message":"hello"}' 2>trace.jsonl
For HTTP/SSE servers, verbose mode also shows raw HTTP headers and timing:
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.
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:
# 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:
const sessionId = await client.getSessionId("github");
// or: (await client.getServerInfo("github")).sessionId
mcpx exec validates tool arguments locally before sending them to the server. MCP tools advertise a JSON Schema for their inputs — mcpx uses this to catch errors fast, without a round-trip.
# Missing required field — caught locally
mcpx exec github create_issue '{"title": "bug"}'
# => error: missing required field "repo" (github/create_issue)
# Wrong type — caught locally
mcpx exec github create_issue '{"repo": "foo", "title": 123}'
# => error: "title" must be a string, got number (github/create_issue)
# Valid — sent to server
mcpx exec github create_issue '{"repo": "foo", "title": "bug"}'
# => { ... }
Validation covers:
If a tool's inputSchema is unavailable (some servers don't provide one), execution proceeds without local validation.
Anything after a -- separator is parsed as shell flags using the tool's input schema for type coercion. This is handy for interactive use — you don't need to remember JSON quoting rules.
# JSON form
mcpx exec github create_issue '{"owner":"arcadeai-labs","repo":"mcpx","title":"bug"}'
# Equivalent shell-flag form
mcpx exec github create_issue -- --owner arcadeai-labs --repo mcpx --title bug
# --field=value also works
mcpx exec github create_issue -- --owner=arcadeai-labs --repo=mcpx --title=bug
# Booleans
mcpx exec my-server flagit -- --enabled # true
mcpx exec my-server flagit -- --no-enabled # false
# Arrays — repeatable flag or comma-split
mcpx exec my-server tag -- --label bug --label todo
mcpx exec my-server tag -- --label bug,todo
Type coercion follows the field's type in the input schema (string, integer, number, boolean, array). Nested objects must use the JSON form. Combining -- shell flags with inline JSON args, --file, or stdin is rejected.
Output is human-friendly by default, JSON when piped:
# Human-readable
mcpx info github
# JSON (piped)
mcpx info github | jq '.tools[].name'
# Force JSON
mcpx info github --json
--format)Tool results (exec, task result) support three output formats via the global --format / -F flag:
# Default JSON output — full MCP response with content array
mcpx exec github search_repositories '{"query":"mcp"}'
# Markdown — rich terminal rendering with colors and formatting
mcpx exec github search_repositories '{"query":"mcp"}' -F markdown
The markdown format extracts text from MCP content blocks and renders it through Bun's built-in markdown parser with ANSI styling — headings, bold/italic, code blocks with borders, colored links, and bullet lists. JSON content is converted to a structured document with headings and bullet lists.
For other commands (list, info, search), --format json forces JSON output and --format markdown uses the existing human-friendly formatting.
Tool results are JSON by default, designed for chaining:
# Search repos and read the first result
mcpx exec github search_repositories '{"query":"mcp"}' \
| jq -r '.content[0].text | fromjson | .items[0].full_name' \
| xargs -I {} mcpx exec github get_file_contents '{"owner":"{}","path":"README.md"}'
# Conditional execution
mcpx exec filesystem list_directory '{"path":"."}' \
| jq -e '.content[0].text | contains("package.json")' \
&& mcpx exec filesystem read_file '{"path":"./package.json"}'
Stdin and file input work for tool arguments:
# Pipe JSON directly
echo '{"path":"./README.md"}' | mcpx exec filesystem read_file
# Pipe from a file
cat params.json | mcpx exec server tool
# Shell redirect from a file
mcpx exec server tool < params.json
# Read args from a file with --file flag
mcpx exec filesystem read_file -f params.json
mcpx ships a Claude Code skill at .claude/skills/mcpx.md that teaches Claude Code how to discover and use MCP tools. Install it:
# Install to the current project (.claude/skills/mcpx.md)
mcpx skill install --claude
# Install globally (~/.claude/skills/mcpx.md)
mcpx skill install --claude --global
# Install to both locations
mcpx skill install --claude --global --project
# Overwrite an existing skill file
mcpx skill install --claude --force
Then in any Claude Code session, the agent can use /mcpx or the skill triggers automatically when the agent needs to interact with external services. The skill instructs the agent to:
mcpx search "<intent>" to find relevant toolsmcpx info <server> <tool> to get the schema before callingmcpx exec <tool> '<json>' to execute (or mcpx exec <server> <tool> '<json>' if the tool name is ambiguous)This keeps tool schemas out of the system prompt entirely. The agent discovers what it needs on-demand, saving tokens and context window space.
mcpx ships a Cursor rule at .cursor/rules/mcpx.mdc that teaches Cursor how to discover and use MCP tools. Install it:
# Install to the current project (.cursor/rules/mcpx.mdc)
mcpx skill install --cursor
# Install globally (~/.cursor/rules/mcpx.mdc)
mcpx skill install --cursor --global
# Install both Claude and Cursor at once
mcpx skill install --claude --cursor
# Overwrite an existing rule file
mcpx skill install --cursor --force
For non-Claude-Code agents, add this to the system prompt:
You have access to MCP tools via the `mcpx` CLI.
To discover tools:
mcpx search "<what you want to do>" # combined keyword + semantic
mcpx search -k "<pattern>" # keyword/glob only
mcpx info <server> <tool> # tool schema
To execute tools:
mcpx exec <tool> '<json args>' # server auto-resolved
mcpx exec <server> <tool> '<json args>' # explicit server
mcpx exec <server> <tool> -- --k=v # shell-flag args (typed via schema)
mcpx exec <server> <tool> -f params.json
Always search before executing — don't assume tool names.
For agents that don't have shell access — remote, persistent, or isolated agents running in TypeScript:
import { McpxClient } from "@arcadeai/mcpx";
const client = new McpxClient();
// or: new McpxClient({ mcp: "v2" }) // official SDK v2 client, pin 2026-07-28
// or: new McpxClient({ mcp: "auto" }) // probe v2, fall back to v1
// or: new McpxClient({ configDir: "/path/to/.mcpx" })
// or: new McpxClient({ servers: { mcpServers: { ... } } })
// 1. Search for tools
const results = await client.search("send a message");
// 2. Inspect the tool schema
const tool = await client.info("arcade", "Slack_SendMessage");
// 3. Execute the tool
const result = await client.exec("arcade", "Slack_SendMessage", {
channel: "#general",
message: "hello",
});
// Also available: listTools, listResources, readResource,
// listPrompts, getPrompt, listTasks, getTask, cancelTask,
// getServerInfo, getServerNames, getSessionId, validateToolInput
await client.close();
The SDK uses the same config files as the CLI (~/.mcpx/servers.json, auth.json, search.json). Server management (add, remove, auth) is done via the CLI — the SDK is read-only.
You can also pass server config directly, bypassing file loading entirely:
const client = new McpxClient({
servers: {
mcpServers: {
local: { command: "node", args: ["server.js"] },
remote: { url: "https://mcp.example.com", mcp: "v2" },
},
},
mcp: "auto", // default for servers that omit `mcp`
});
info() and listTools() return the raw MCP Tool, so you get everything the server declares: name, title, description, inputSchema, outputSchema, execution.taskSupport, and annotations. The annotations object carries the MCP behavioral hints:
const tool = await client.info("github", "delete_repo");
tool?.annotations; // { title?, readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }
⚠️ Annotations are untrusted hints — per the MCP spec, clients should never make tool-use decisions based on annotations from untrusted servers. Treat the approval gate below as a guardrail, not a security boundary.
Because the SDK runs non-interactively, mcpx can't prompt a human itself — instead you supply an approval callback and a policy for which tools to gate. This lets you require approval before, say, any open-world writeable tool (openWorldHint: true and not readOnlyHint) runs:
import { McpxClient, ToolApprovalDeniedError } from "@arcadeai/mcpx";
const client = new McpxClient({
servers: { mcpServers: { github: { url: "https://mcp.github.com" } } },
approvalPolicy: "open-world-writeable", // default is "none"
onApprovalRequired: async ({ server, tool, args, annotations, reason }) => {
// Prompt a human, call out to an approval service, check a policy, etc.
return await promptHuman(`Allow ${server}/${tool}? (${reason})`, args);
},
});
// Gated tools wait for the callback; returning false throws ToolApprovalDeniedError.
// If a tool is gated but no onApprovalRequired callback was provided, exec() throws
// ToolApprovalRequiredError (fail-closed).
await client.exec("github", "delete_repo", { repo: "old-thing" });
approvalPolicy accepts:
Helpers isOpenWorldWriteable(tool) and isWriteable(tool) are exported for building custom predicates, along with the ToolAnnotations type. mcpx info <server> <tool> also surfaces these hints in the CLI.
Gating a specific tool by name. The annotation presets can't tell two similar tools apart — a "create PR" and a "create issue" tool both look like open-world writes. To gate one but not the other, use the custom predicate form and match on tool.name (and server):
const client = new McpxClient({
servers: { mcpServers: { github: { url: "https://mcp.github.com" } } },
// Require approval ONLY for creating PRs — issue creation runs freely.
approvalPolicy: (tool, server) => server === "github" && tool.name === "create_pull_request",
onApprovalRequired: async ({ server, tool, args }) => await promptHuman(`Allow ${server}/${tool}?`, args),
});
await client.exec("github", "create_pull_request", { ... }); // waits for approval
await client.exec("github", "create_issue", { ... }); // runs immediately, no prompt
Confirm the exact tool.name first — it must match exactly, and servers name tools differently (e.g. create_pull_request vs github_create_pr):
mcpx search "open pull request" # find the tool and its server
mcpx info github create_pull_request # confirm the name
To match a family of tools, use a regex (/pull_request|merge_pr/.test(tool.name)); to gate the PR tool and everything open-world-writeable, combine them with the array form: ["open-world-writeable", (tool, server) => …]. Matching on tool.name is reliable — unlike annotations, which are untrusted server-supplied hints.
AI agents like Claude Code and Cursor prompt users to approve each mcpx exec call. mcpx allow and mcpx deny manage fine-grained permission rules so agents can self-authorize specific tools without broad access.
Key insight: If the user allows the initial permission pattern once (safe — it only writes to local settings files), the agent can then grant itself access to specific tools as needed. This is an opt-in workflow — by default, agents cannot self-authorize and will prompt the user for each mcpx exec call.
# Allow all tools on a server (Claude Code, default)
mcpx allow github
# Allow for Cursor instead
mcpx allow github --cursor
# Allow specific tools only
mcpx allow github search_repositories get_file
# Allow read-only commands (search, info, list, servers, ping, etc.)
mcpx allow --all-read
# Allow all mcpx exec calls
mcpx allow --all
# Show current permissions across all scopes
mcpx allow --list
mcpx allow --list --cursor
# Preview what would be written
mcpx allow github --dry-run
# Revoke a server's permissions
mcpx deny github
# Revoke all mcpx permissions
mcpx deny --all
Target flag — by default, permissions target Claude Code. Use --cursor to target Cursor instead:
Scope flags control where the permission is written:
allow options:
deny options:
# Install dependencies
bun install
# Run in development
bun run dev
# Run tests
bun test
# Build single binary
bun run build
# Lint
bun lint
Inspired by mcp-cli by Phil Schmid, which nails the core DX of a shell-friendly MCP client. mcpx extends that foundation with OAuth support for HTTP servers and semantic tool search.
mcpx is the client. If you need the server side — auth, governance, and production tools at scale — check out Arcade.
The full story: curl for MCP: Why Coding Agents Are Happier Using the CLI
MIT
A command-line interface for MCP servers. curl for MCP.
{ "mcpServers": { "arcadeai-mcpx": { "command": "npx", "args": [ "-y", "@arcadeai/[email protected]" ] } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
@arcadeai/mcpx se ejecuta localmente por stdio.
Última comprobación: 2026-11-15. A command-line interface for MCP servers. curl for MCP.