Add, inspect, and remove MCP servers

piagent-mcp provides deterministic add, remove, get, list, enable, and disable operations across all four scopes.

Two surfaces for two contexts

Inside a Pi session, use the slash command. In a terminal, use the CLI. Both read the same state; the difference is where the operation runs.

Task	In a session	In a terminal
Open the menu	/piagent-mcp	—
List servers and state	/piagent-mcp status	piagent-mcp list
Inspect one server	/piagent-mcp get <name>	piagent-mcp get <name>
Show readiness blockers	/piagent-mcp doctor	piagent-mcp doctor
Approve a repository server	/piagent-mcp approve <name>	piagent-mcp approve <name>
Enable or disable	/piagent-mcp enable\|disable <name>	piagent-mcp enable\|disable <name>
Add, remove, or seed a preset	—	piagent-mcp add\|remove\|--preset
Live connection state or OAuth	/mcp, /mcp-auth	—

Why use a slash command instead of invoking the CLI in-session

Asking the model to run piagent-mcp list through bash spends model turns executing, reading, and restating data that the current process already has. Pi dispatches the slash command directly to its handler: no model tokens, no interpretation, and a deterministic response.

Adding a server remains terminal-only

add includes shell quoting, ${VAR} references, and a command line after --. The shell already parses these correctly. Reimplementing that parser in a slash command would create a second, weaker grammar. /piagent-mcp add prints the exact terminal command to run.

Commands

In a session

No arguments opens the menu. Direct commands support Tab completion for subcommands and server names.

/piagent-mcp                 menu
/piagent-mcp status          full table
/piagent-mcp get sentry
/piagent-mcp doctor
/piagent-mcp approve internal

Add a server

Use --url for a remote server, or place a local server command after --. Run this in a terminal.

piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp

Inspect

list shows every server visible from the current project and its state. get shows one server in detail.

piagent-mcp list
piagent-mcp get sentry

Disable and remove

disable preserves the definition but stops using it. remove deletes it from a scope.

piagent-mcp disable sentry
piagent-mcp enable sentry
piagent-mcp remove sentry --scope global

Preset

Seed a pinned group of servers. --replace returns preset-owned servers to their baseline.

piagent-mcp --preset core --scope global --replace
piagent-mcp --list

Output names the modified file

All four configuration layers are read, so the first debugging question is which file is active. add answers that directly:

$ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
Added local MCP server internal with command: npx -y @acme/internal-mcp in project scope
File modified: /Users/you/repo/.mcp.json
This scope is part of the repository, so the server is not usable until approved: piagent-mcp approve internal

list renders a table whose STATE column identifies immediately usable servers:

NAME             SCOPE    TRANSPORT  TARGET                                  STATE
context7         global   stdio      npx -y @upstash/context7-mcp@3.2.4       ready
chrome-devtools  global   stdio      npx -y chrome-devtools-mcp@1.6.0 ...     ready
github           global   stdio      docker run -i --rm -e GITHUB_PERSON...   needs-env
internal         project  stdio      npx -y @acme/internal-mcp               pending-approval

Custom servers and updates

Each piagent-update reapplies the selected preset with --replace. The merge touches only server IDs owned by that preset.

Preserved

Custom IDs such as my-internal or sentry survive every update.

Replaced

Manual edits to preset-owned IDs such as github or context7 return to baseline on the next update. Use a distinct ID for a custom variant.