mcpx MCP server
Commit Nov 13, 2026Turns registered MCP servers into an agent-friendly command line interface with schema discovery and OAuth support.
Also known as celados/mcpx
- Stars
- 18
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is mcpx MCP?
mcpx turns registered MCP servers into an agent-friendly command line interface with schema discovery and OAuth support.
Summary generated from the project's README
About mcpx MCP server
Developers building agentic workflows can use mcpx to transform registered MCP servers into a structured command line interface. By converting various MCP servers into root commands using dotted paths, it provides a stable and explicit surface for AI agents to interact with tools. The tool manages a global registry of servers, handles schema discovery through a local cache, and supports both HTTP and stdio transports. For local stdio servers, a background daemon called mcpxd keeps sessions warm to improve performance.
Setting up the environment requires Bun on macOS or Linux. Users register servers using the @add command, which can include bearer tokens or environment variable references to keep secrets secure. The system handles complex authentication automatically, including OAuth flows that can trigger browser-based sign-ins when tokens expire or require new scopes. It also allows for the generation of project-specific skills that guide agents on which global servers to use for specific tasks.
What you can do with it
- 1Execute remote tool commandsAn agent can retrieve specific project data from PostHog using a single structured command.
- 2Automate OAuth authenticationThe system can automatically discover authorization servers and handle sign-in challenges when a tool requires credentials.
- 3Generate agent instructionsYou can create local documentation that tells an AI agent exactly which servers are available for a project.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
OPEN_DESIGN_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecelados/mcpx is public and reachablegithub.com/celados/mcpx ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/celados/mcpx ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcpx
mcpx is a command line tool that turns registered MCP servers into an agent-friendly command surface.
It keeps MCP server registrations in a global user registry, discovers tool schemas, handles OAuth where possible, and exposes each MCP server as a root command:
mcpx posthog.projects-get
mcpx sentry.search-issues '{"query":"is:unresolved"}'
mcpx is designed for agents. The command surface is intentionally schema-first,
stable, and explicit: commands use dotted paths and receive one structured input
token, while mcpx's own control commands live under the @ namespace.
Requirements
- Bun
- macOS, Linux, or any environment that can run Bun executables
Install
Install the latest release:
curl -fsSL https://raw.githubusercontent.com/celados/mcpx/main/install.sh | bash
By default, the installer downloads the executable JS bundle from GitHub Releases
and installs it to ~/.local/bin/mcpx.
Set MCPX_INSTALL_DIR to choose another install directory.
Add MCP Servers
Register MCP servers globally:
mcpx @add "{ name: 'posthog', url: 'https://mcp.posthog.com/mcp' }"
mcpx @add "{ name: 'sentry', url: 'https://mcp.sentry.dev/mcp' }"
mcpx @add "{ name: 'cf-docs', url: 'https://docs.mcp.cloudflare.com/mcp' }"
mcpx @add "{ name: 'cf-bindings', url: 'https://bindings.mcp.cloudflare.com/mcp' }"
mcpx @add "{ name: 'cf-observability', url: 'https://observability.mcp.cloudflare.com/mcp' }"
mcpx @add "{ name: 'browser', url: 'http://127.0.0.1:9000/mcp' }"
browser-os is an agent-native browser built on Chrome. It exposes a local MCP server that lets agents control the browser directly — navigating pages, extracting content, and interacting with web UIs.
mcpx keeps its state under ~/.agents/mcpx/state-v2/: server declarations in
registry.json, credentials (OAuth grants, bearer values, secret headers) in
credentials.json, and observed tool schemas in schema-cache.json. The MCP
Runtime is the only writer.
Project directories do not need MCP config files. A project should decide which global servers are relevant by using schema selectors or a generated skill.
Call Tools
Call tools through the server command:
mcpx <server>.<tool> '<json-or-json5>'
Examples:
mcpx posthog.projects-get '{}'
mcpx sentry.whoami '{}'
For complex payloads, put the whole object on stdin as YAML — block scalars need no escaping:
mcpx cf-graphql.graphql_query - <<'EOF'
query: |
query GetWorkerAnalytics($accountTag: String!, $scriptName: String!, $since: Time!, $until: Time!) {
viewer { accounts(filter: {accountTag: $accountTag}) {
workersInvocationsAdaptive(limit: 1000, filter: {scriptName: $scriptName, datetime_geq: $since, datetime_leq: $until}, orderBy: [datetimeHour_ASC]) {
dimensions { datetimeHour scriptName status }
sum { requests subrequests errors duration }
quantiles { cpuTimeP50 cpuTimeP99 }
}
} }
}
operationName: GetWorkerAnalytics
variables:
accountTag: abc123def456
scriptName: my-worker
since: "2026-04-20T00:00:00Z"
until: "2026-04-27T00:00:00Z"
EOF
The command accepts exactly one input object: inline JSON5, or the whole object
from @file / - stdin as YAML (JSON5 when it starts with {). Field values
are literal; there is no per-field - / @path.
Discover Schemas
Print the command schema for agents:
mcpx @schema
Focus on one server:
mcpx @schema .posthog
Focus on a set of servers:
mcpx @schema '.{posthog,sentry}'
Focus on an internal mcpx command:
mcpx @schema '.["@add"]'
mcpx caches discovered tool schemas so commands and @schema answer without
asking the server. The cache is a hint, not the authority, and repairs itself
(ADR 0011):
- calling a tool the cache does not know, or omitting a field the cached schema requires, re-lists that server before the call is rejected;
- a server's Invalid Params rejection, a new session (for schemas over an hour
old) and
tools/list_changedre-list it in the background; mcpxdre-lists every schema older than a week when it starts and daily while it runs.
Background listings never open a browser; there is no manual refresh command.
Control Commands
mcpx control commands use the @ namespace so they do not collide with server
names:
mcpx @add "{ name: '<server>', url: '<mcp-url>' }"
mcpx @add "{ name: '<server>', url: '<mcp-url>', bearer: 'env:<TOKEN_ENV>' }"
mcpx @add "{ name: '<server>', transport: 'stdio', command: '<command>', args: ['<arg>'] }"
mcpx @remove "{ name: '<server>' }"
mcpx @login "{ name: '<server>' }"
mcpx @daemon.status
mcpx @daemon.stop
mcpx @daemon.server
mcpx @skill
mcpx @skill-install
Server names cannot start with @.
HTTP is the default transport. Pass bearer credentials as a string or array.
env:NAME reads a token from an environment variable at runtime; literal values
are accepted but are stored in the registry:
mcpx @add "{ name: 'posthog', url: 'https://mcp.posthog.com/mcp', bearer: 'env:POSTHOG_TOKEN' }"
mcpx @add "{ name: 'posthog', url: 'https://mcp.posthog.com/mcp', bearer: ['env:POSTHOG_TOKEN_A', 'env:POSTHOG_TOKEN_B'] }"
Multiple bearer credentials use round-robin selection by default. Stdio servers
are local process registrations with structured args and env:
mcpx @add '{
"name": "open-design",
"transport": "stdio",
"command": "node",
"args": ["/path/to/open-design/apps/daemon/dist/cli.js", "mcp"],
"env": { "OPEN_DESIGN_TOKEN": "..." }
}'
Stdio servers are called through mcpxd, a user-local daemon that reuses stdio
MCP sessions across CLI invocations. mcpxd starts on demand, keeps idle stdio
servers warm, and can be inspected or stopped with mcpx @daemon.status and
mcpx @daemon.stop. The daemon process is started through the explicit
mcpx @daemon.server subcommand. HTTP servers continue to use the direct client path.
Authentication
Bearer auth is configured explicitly in the @add input. Prefer env:NAME
references so secrets stay out of the registry. ${NAME} is also accepted when
passed through the shell literally.
When several bearer credentials are registered, mcpx advances a local
round-robin cursor before each HTTP request.
OAuth follows the MCP authorization spec through the official MCP SDK. A server
does not need to declare OAuth up front: whenever it answers a request with
401 and a WWW-Authenticate: Bearer resource_metadata=… challenge, mcpx
discovers its authorization server from that challenge, authorizes, records
the server as OAuth, and retries the request. This covers servers whose tools
are partly anonymous — @add lists their tools without credentials, and the
first call to a protected tool starts sign-in. A 403 insufficient_scope
challenge re-authorizes with the additional scope the same way. When @add
itself is challenged, it signs in right away and then lists the tools.
To switch accounts, run mcpx @login "{ name: '<server>' }". It opens a new
browser sign-in (with OIDC prompt=login, so the old browser session is not
reused silently) and replaces the stored grant only once the new sign-in
succeeds.
For OAuth servers that support dynamic client registration, mcpx registers a client automatically for each browser sign-in.
For OAuth servers that do not support dynamic client registration, mcpx prompts for a manual client_id and client_secret. These providers
usually require a preconfigured redirect URL. mcpx uses:
http://127.0.0.1:65245/callback
Add and save that exact Redirect URL in the provider app settings before continuing the prompt.
OAuth credentials repair themselves during ordinary tool calls:
- When a token is close to expiry, mcpx refreshes it silently before the call.
- When the server rejects a token with 401, mcpx refreshes it and retries the call once. Another call that already replaced the token is not undone.
- When no refresh is possible (no token yet, or the refresh grant was revoked), the call opens browser authorization, prints the authorization URL to stderr, and waits up to 5 minutes for it to complete before continuing. Concurrent calls for the same server share one authorization.
Providers that need a manual OAuth client can only prompt in an interactive
terminal; without one, the call fails immediately with reauth-required and
mcpx @login "{ name: '<server>' }" must be run in a terminal.
Tool calls use a 5 minute request timeout by default. Set
MCPX_TOOL_CALL_TIMEOUT_MS when a remote MCP server legitimately needs longer.
mcpx buffers MCP subscription notifications and returns them with the next daemon
tool-call result by default. Set MCPX_NOTIFICATION_MODE=discard to ignore those
notifications for a command; accepted values are buffer and discard.
Output
mcpx optimizes output for humans and agents by default:
- text MCP content is printed directly
- JSON text content is rendered as YAML
- non-text content is saved to a temporary file and printed as
file saved <path> - supplemental MCP
structuredContentis printed as$structuredonly when it is not already represented by the primary content
Use argc context to preserve raw server output:
mcpx posthog.projects-get --context "{ output: 'raw' }"
Project Skills
Generate a project-local skill that tells agents which global MCP servers to use:
mcpx @skill-install "{ servers: 'posthog,sentry' }"
This writes:
.agents/skills/mcpx/SKILL.md
.agents/skills/mcpx/references/install.md
.agents/skills/mcpx/references/servers.md
The generated skill instructs agents to discover tools with focused schema
selectors and call MCP tools through mcpx. A Troubleshooting section at the
bottom points collaborators at install and server-setup references so their
agent can recover when mcpx is missing or a listed server is not registered.
For temporary agent guidance without writing .agents/skills, print a one-server
skill to stdout:
mcpx @skill-install "{ show: 'sentry' }"
Skill
General mcpx skill definition lives at src/index.md (served by mcpx @skill).
License
MIT
mcpx MCP questions
How does mcpx handle authentication for MCP servers?
mcpx supports bearer authentication via environment variables and handles OAuth automatically by discovering authorization servers from 401 challenges.