# Mcpx

> Use when the user needs to discover or call already-configured MCP servers through the mcpx CLI, including generating project-local MCP routing skills.

- **Type:** Skill
- **Install:** `agentstack add skill-celados-mcpx-mcpx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [celados](https://agentstack.voostack.com/s/celados)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [celados](https://github.com/celados)
- **Source:** https://github.com/celados/mcpx/tree/main/skills/mcpx

## Install

```sh
agentstack add skill-celados-mcpx-mcpx
```

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

## About

# mcpx

`mcpx` turns registered MCP servers into an agent-friendly command surface.
Use it when a task needs MCP-backed services such as PostHog, Sentry, Cloudflare,
or another server registered in the user's global mcpx registry.

## Execution Rules

- Run `mcpx` directly.
- Start with the server inventory instead of dumping every registered schema.
- Call MCP tools as `mcpx   --input `.
- Pass all tool arguments through `--input`; do not invent flags for MCP tool fields.
- Use focused schema selectors before calling tools on large MCP surfaces.
- Do not hand-edit `~/.agents/mcpx/servers.json` or token cache files unless the user explicitly asks for registry surgery.
- Treat MCP server registration and OAuth setup as human-owned configuration. If a required server is missing or unauthenticated, stop and ask the user to configure it.

## First Move: Discover The Surface

At the start of an MCP task, run bare `mcpx` to list configured servers:

```bash
mcpx
```

Choose the likely server from the user's request, then inspect only that server's
schema:

```bash
mcpx --schema=.sentry
mcpx --schema=.posthog
```

After that, narrow to the specific tool or a short candidate list:

```bash
mcpx --schema=.posthog.projects-get
mcpx --schema='.posthog.{projects-get,alerts-list,alert-create}'
```

Avoid `mcpx --schema` unless the user explicitly asks for the complete command
surface. On a real registry it may expand every server schema and waste the
agent context.

## Call Tools

Use inline JSON/JSON5 for tiny inputs:

```bash
mcpx posthog projects-get --input '{}'
mcpx sentry search-issues --input '{"query":"is:unresolved"}'
```

For non-trivial payloads, prefer `@file` or heredoc input:

```bash
mcpx   --input @payload.json

mcpx   --input @- `). Use `--raw` to
disable that optimization. When a tool emits notifications, `--raw` output may
also include a JSON envelope — see Notifications below.

## Server Transports

mcpx supports two MCP transports, both configured through `mcpx @add`:

- **HTTP** — default. Remote MCP services like PostHog or Sentry.
- **Stdio** — local processes started by mcpx, for example
  `mcpx @add --name fs --transport stdio --command bunx --args -y --args @modelcontextprotocol/server-filesystem --args /tmp/fs-sandbox`.

HTTP bearer auth uses `--bearer`. Prefer `env:NAME` so secrets stay out of the
registry. Repeat `--bearer` for multiple credentials; mcpx uses round-robin by
default:

```bash
mcpx @add --name posthog --url https://mcp.posthog.com/mcp \
  --bearer env:POSTHOG_TOKEN_A \
  --bearer env:POSTHOG_TOKEN_B
```

After registration both behave identically from the agent's view: same schema
discovery, same `mcpx   --input ...` call pattern, same output
shape. You do not need to differentiate when calling tools.

## Notifications

Most tools emit no notifications and this section never applies.

When an MCP server emits events during a call (progress reporting, server-side
state changes, custom events), mcpx merges them into default structured output
under an injected `$notifications` field:

```yaml
count: 1
$notifications:
  - method: notifications/progress
    params:
      progressToken: '...'
      progress: 3
      total: 4
      message: step 3
```

For non-JSON text, binary, or mixed content, mcpx falls back to the trailing
sentinel line:

```

$notification: [{"method":"notifications/progress","params":{...}}]
```

Notifications are objects with these fields:

- `method` — MCP notification method name
- `params` — method-specific payload (shape depends on `method`)
- `aggregatedCount` — only on the **last** `notifications/progress` entry per
  progress token; indicates that N intermediate progress entries were collapsed
  to keep output bounded. The first and last entries are preserved verbatim.

Notification methods you may encounter:

| method                                | meaning                                                                                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notifications/progress`              | Progress for a long-running tool. Carries `{ progressToken, progress, total?, message? }`.                                                               |
| `notifications/tools/list_changed`    | Server's tool schema changed. mcpx automatically refreshes the registry; you do not need to react.                                                       |
| `$oversize`                           | Synthetic raw-mode marker. Means notifications were saved to a temp JSON file. Default output renders this as `notifications oversize, saved to `. |
| other (e.g. `notifications/custom/*`) | Passed through verbatim. Server-specific.                                                                                                                |

In `--raw` mode with a structured result and non-empty notifications, the
trailing sentinel line is replaced by a JSON envelope on stdout:

```json
{ "result": , "notifications": [ ... ] }
```

Text results keep the trailing `$notification:` line even under `--raw`,
because text content is not JSON and wrapping it would break consumers.

Practical guidance:

- If your task does not depend on progress or server events, ignore notifications.
- Check `$notifications`, the sentinel line, or the raw envelope only when present.
- Do not assume notifications appear; the common case is no `$notification:` at all.

## Project-Local Skills

When the user has already configured the relevant global MCP servers and wants a
project to expose only that approved set to agents, generate a project-local mcpx
skill:

```bash
mcpx @skill --servers posthog,sentry
```

This writes:

```text
.agents/skills/mcpx/SKILL.md
```

Use the generated project skill as the project-specific router. It should name
servers the user has already made available; do not use this flow to register or
authenticate new MCP servers.

For temporary agent guidance without writing `.agents/skills`, print a
single-server skill to stdout:

```bash
mcpx @skill --show slack
```

Use this when the user asks for a one-off service action during the current
agent session and does not want persistent project skills.

## References

mcpx maintains a background daemon (`mcpxd`) for session reuse and notification
buffering. You normally do not need to interact with it. If a tool call behaves
unexpectedly (stuck session, surprising eviction, schema drift), see
[references/daemon.md](references/daemon.md) before filing an issue.

## Feedback

If mcpx behaves unexpectedly, capture the exact command, schema selector, input,
and structured error, then file an issue:

```bash
gh issue create -R celados/mcpx --title "bug: " --body ""
```

## Source & license

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

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

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

## Links

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