Apx Mcp

---
name: apx-mcp
description: Register, list, debug, scope MCP servers in APX. Load BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics. Triggers: 'add MCP', 'apx mcp', 'MCP scope', 'MCP failing', 'list MCPs'.
---

# apx-mcp

APX exposes MCP servers via three scopes; resolution priority **runtime > shared > global**, conflicts via `apx mcp check`:

| Scope | File | Committed? | Secrets OK? | When |
|---|---|---|---|---|
| `shared` | `<repo>/.apc/mcps.json` | yes | **no** | Team-wide (filesystem, brave, github public) |
| `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project — tokens, machine-specific endpoints |
| `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide, not tied to a project |

## Super-agent tool

The super-agent registers an MCP with the **`add_mcp`** tool (name + `command`/`args`/`env` for stdio, or `url`/`headers` for http; `scope` = runtime | shared | global, default runtime) — no shelling to `apx mcp add`. Give it a one-line `description` of what it is for: agents see it (plus the tools it offered last time it was listed) next to the name in their per-turn project context and in `list_mcps`. Then `list_mcp_tools` to see what it exposes and `call_mcp` to run one. Secrets go in `runtime`/`global` scope, never `shared` (committed).

## Concrete CLI calls

```bash
# List (defaults to all scopes)
apx mcp list --project acme
apx mcp list --scope runtime --project acme
apx mcp list --scope shared  --project acme
apx mcp list --scope global

# Inspect sources and conflicts
apx mcp check --project acme

# Add — shared (commit to repo)
apx mcp add filesystem --command npx --project acme \
  -- -y @modelcontextprotocol/server-filesystem .

# Add — runtime (per-project, local, secrets safe)
apx mcp add github --scope runtime --project acme \
  --command npx --env GITHUB_TOKEN=ghp_xxx \
  -- -y @modelcontextprotocol/server-github

# Add — global (machine-wide)
apx mcp add brave --scope global \
  --command npx --env BRAVE_API_KEY=BSAxxx \
  -- -y @modelcontextprotocol/server-brave-search

# Remove (pass --scope when not in default: shared inside APC project, else global)
apx mcp remove filesystem --project acme
apx mcp remove github     --scope runtime --project acme

# Toggle (defaults to owning scope)
apx mcp enable  filesystem --project acme
apx mcp disable filesystem --project acme

# Discover tools — list catalog, then inspect one tool's schema
apx mcp tools filesystem                     # table: tool name + description
apx mcp tools filesystem read_file           # params (types, required) + run example
apx mcp tools filesystem --json              # raw JSON with full inputSchema

# Call a tool through the daemon
apx mcp run filesystem read_file '{"path":"README.md"}'
```

## Scope decision tree

1. **Has secrets/tokens?** → `runtime`. Always.
2. **Part of project's shared dev environment?** → `shared` (committed).
3. **Used across all your projects?** → `global`.

Default if unclear: `shared` inside an APC project, `global` outside.

## Command shapes by transport

Two transports. `--command` = local process (stdio), `--url` = remote endpoint (http).
There is no third option, and no flag outside this list — if a shape isn't here,
run `apx help mcp add` instead of guessing.

```bash
# stdio MCP — a local process (npx, uvx, node, python)
apx mcp add <name> --command npx -- -y <package-or-flag-list>
apx mcp add <name> --command uvx -- <python-cli-name>
apx mcp add <name> --command python -- /abs/path/to/server.py

# stdio env vars (one --env per var)
apx mcp add <name> --command npx \
  --env GITHUB_TOKEN=ghp_xxx \
  --env GITHUB_OWNER=acme \
  -- -y @modelcontextprotocol/server-github

# http MCP — a remote streamable-HTTP endpoint. No command, no npx, no install.
apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime

# http with auth headers (repeatable; "Name: value" or Name=value both parse)
apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime \
  --header "Authorization: Bearer $TOKEN" \
  --header "X-Workspace: acme"
```

Everything after `--` is forwarded verbatim as args to a stdio command. Quote carefully.
`--env` and `--` args are stdio-only; `--header` is http-only — mixing them errors.

Remote servers almost always carry a token, so they belong in `--scope runtime`
(chmod 0600, never committed). Read the token from the environment rather than
pasting it: `--header "Authorization: Bearer $TOKEN"`.

## After adding: prove it works

```bash
apx mcp tools <name>     # spawns/connects and lists tools — this is the real check
apx mcp logs <name>      # if the above is empty or errors: request/response log
```

`apx mcp add` only writes JSON — it never contacts the server. An MCP that "was
added fine" but has no tools is a failed connection, not a successful install.

## Anti-examples

```bash
# DON'T put tokens in shared scope — it commits.
apx mcp add github --scope shared --env GITHUB_TOKEN=ghp_xxx ...
# ↑ Token ends up in .apc/mcps.json in your repo. Use --scope runtime.

# DON'T remove from the wrong scope — daemon returns 409 with the right scope.
apx mcp remove github          # errors if github lives in runtime

# DON'T expect IDE-foreign configs (~/.cursor/mcps.json, ~/.claude/mcps.json)
# to be removable via apx mcp remove. APX reads them advisory (source=cursor/claude)
# but won't write them. Edit the IDE config directly.
```

## Debugging

```bash
apx mcp check --project acme      # scopes seen + which files exist
apx mcp tools <name>                 # spawn server + list its tools (proves init works)
apx mcp logs <name>                  # spawn/init event log + stderr tail
apx mcp run <name> <tool> '{...}'    # call a tool for real
apx log -f                           # tail unified log for spawn errors
```

"Doesn't show tools" = command failed to start (missing env vars, package not found) or crashed during initialize. `apx mcp logs <name>` shows the stderr tail; the unified log has the rest.

Standard workflow to use any MCP: `apx mcp tools <name>` → `apx mcp tools <name> <tool>` (copy the run example) → `apx mcp run <name> <tool> '<json>'`.

## Don't

- Don't mix scopes for the same MCP name unless you want shadowing — highest priority wins, others stay invisible.
- Don't edit `~/.apx/projects/<id>/mcps.json` by hand; use `apx mcp add --scope runtime` (the file is chmod 0600 — CLI preserves it).
- Don't put tokens via `--env KEY=` inline if shell history is public. Set them in your shell first, then `--env KEY=$KEY`.
- Don't forget to `apx daemon reload` after hand-editing JSON. `apx mcp` does this for you.