---
name: help-how-to-mcp
description: Use Po MCP to inspect domain-scoped servers, authenticate, reload configuration, measure what server tool schemas cost in context, and troubleshoot tool availability.
---

# Use Po MCP

Use MCP when a task depends on a configured external server, proxy upstream, or tool selected by the active Po domains.

## Named tools and accounts

Main and native child agents receive permitted direct tool names, descriptions and complete input schemas.
Use the advertised registered name: configured entries `personal` and `work` exposing `search` become
`personal_search` and `work_search`, even at the same endpoint. Each entry uses its own connection and
configured-name credential slot. Never infer dispatch identity by splitting the prefix.

Children borrow the parent's tools. The direct connection-management tool is main-agent-only;
borrowed trusted `exec` still binds to the parent's session. `mcp` and `mcp_use` requests
expand into permitted direct tools; configured-server or `server/tool` selectors narrow access.
Capability ceilings require explicit MCP permission and still constrain exact tool grants.

## Po MCP namespace

Code mode's `mcp` namespace is taught by the `codemode-how-to-mcp` skill, which is always
active. Pi's internal MCP codemode and tool search remain disabled. These are separate
mechanisms, also distinct from code mode run by a remote MCP client. While code mode is
bound, the main agent's direct tools for these servers are withdrawn (Context lists them as
inactive), MCP Apps' tools included. An App tool called from `exec` keeps its App: Po saves the
result as an `mcp.app.codemode` session entry and the call's card opens the App from it, and the
App's own tool calls still run after the person confirms them. Without code mode every direct
tool and the `mcp_use` compatibility route remain. The namespace does not change MCP access grants.

## Remote MCP connection

This connection already belongs to one Po session. Use the tools actually
exposed by its selected domains. Prefer a named upstream tool with its declared
schema. Use `mcp_use` only when the server name, tool name, and arguments have
been discovered from a trusted catalog; never guess them.

The commands below are local Po interfaces, not Bash commands or MCP tools.
If status, authentication, or reload is not exposed, explain which local action
the user needs to take. Do not read private credentials or create another session
to work around an unavailable capability. Tool/resource support in a packaged
ChatGPT plugin does not establish support in this MCP connection.

## Local Po: inspect and operate

- Run `/mcp` for the interactive overlay.
- Run `/mcp status` to inspect configured servers, connection state, and diagnostics.
- Run `/mcp auth <server>` when a server requires OAuth authorization.
- Run `/mcp reload` after changing MCP configuration.

The web Context panel also offers authorization and management actions. Headless hosts never open a desktop browser automatically; use the provider link in Context or the reported authorization URL.

## Test a URL server without saving it

Ask the person for permission before connecting. Help mode is not approval.
In Help mode, discover `mcpTest` and call `await mcpTest.add({name, url, type: 'http'})`
(or `type: 'sse'`). Optional headers and OAuth client settings use the discovered schema.
Never paste literal secrets into tool arguments or code: conversation history can persist them.
Use `${ENV_VAR}` references from the admitted session environment for sensitive settings.
In configured servers, prefer `${vault:NAME}` references in header values, env values and
`bearerToken`. Agents never write secret values: ask the person to enter a missing secret in the
session MCP panel ("needs secret NAME").
Without code mode, use the main-agent-only `mcp_test_server` tool with `action: 'add'` and `server`.

Add waits for connection and OAuth completion. If sign-in is needed, ask the person to open
the MCP servers panel and follow its link. Use a long enough `exec` timeout or a background
exec for browser sign-in. Cancellation removes the unfinished addition. Never paste secrets
or authorization codes into the conversation.

`mcpTest.list()` lists only session-added servers. `mcpTest.remove(name)` disconnects one and
forgets its memory credentials. Entries, headers and credentials never go into MCP config,
the Po vault, credential files or the shared definitions cache. Reload retains them; ending the
session forgets them. Turning Help off hides management but leaves already-added servers
connected. MCP disabled with `--no-mcp` remains disabled. No stdio or `/mcp add` is supported.

## Inspect schema cost and domain selection

Permitted direct tools contribute names, descriptions and full input schemas to native child model context, and to the main agent's unless code mode is bound (then none do). Context shows the active declarations and estimated schema cost; a withdrawn tool shows as inactive.

- Run `po --explain` to inspect per-server schema estimates. Figures come from a real handshake and are cached, so the first run for a new server descriptor is slower than later ones.
- Compare declarations with `po --domains <name[,name...]> --explain`.
- Control server availability with an `mcp.servers` allowlist in `.po/domains.yaml` rather than deleting servers from `.mcp.json`, which keeps them available to other domains.

Keep catalogs out of prompt prose and narrow child subsets. Filtering activates only when every selected domain declares `mcp`. A selection that mixes an allowlisted domain with one that omits `mcp` stays unfiltered.

## Troubleshoot missing tools

1. Confirm the server exists in repository `.mcp.json`, a valid Agent Plugin `mcp.json`, or `mcp-config.yaml` for proxy upstreams.
2. Confirm the active `.po/domains.yaml` selection permits the direct server or proxy upstream.
3. Check `/mcp status` diagnostics before changing configuration.
4. Reload after a valid change, then confirm the tool catalog again.
5. If Po was launched with `--no-mcp`, keep MCP disabled unless the user explicitly starts a new session without that flag.
6. A server in the `closed`, `degraded`, `failed` or `needs-auth` state is withheld from direct tools, the `mcp` namespace and `codemode-how-to-mcp` until it reconnects. After `/mcp disconnect <server>` it stays hidden, even across `/mcp reload` and session restarts (saved as an `mcp.session.state` transcript entry), until `/mcp auth <server>`, a supplied secret or a reconnect. Removing a server in settings drops it from every live session whose copy came from that file.

## Approval for tools that change data

MCP tools that are not marked `readOnlyHint: true` or `destructiveHint: false` go through Po's approval gate before they run, from direct tools, `mcp_use`, the code-mode `mcp` namespace and MCP App calls. The request is non-blocking: the agent keeps working and the call runs once approved.

- Host-wide switch: "Run destructive MCP tools without asking" in MCP settings, saved as `autoApproveDestructiveTools` in `<po home>/mcp-settings.json`. It applies to every session at once.
- Session switch: `/mcp approve on|off|status`. It is saved with the session, so it survives a restart.
- Either switch skips the prompt. An MCP App call the person already confirmed in the App is not asked twice.
- Subagents, background execs and unattended runs are not asked; they run directly. Keep auto-approve off unless the person wants it.
- The edge host has neither switch, so its destructive tools always ask.
  Domain filtering happens before disallowed stdio processes are spawned. Treat allowed stdio configuration as executable code because it runs with the Pi process environment and operating-system privileges. Keep OAuth stores and emitted configuration private.

## Session file transfer

Use advertised `share_file({path})` for a short-lived public link to a session file,
not an absolute host path as an attachment. It needs remote access and returns
URL, file name, MIME, size, expiry, and a three-download limit without a consent
prompt. Outbound file parameters to other MCP servers still ask consent.

`save_file` accepts exactly one `file` form: a public HTTPS
`{download_url,file_name,file_id?,mime_type?}` (25 MiB maximum), or
`{name,data_base64}` (5 MiB decoded maximum). Default storage is private session
attachments. Optional relative `path` writes a new file in the bound cwd through
existing non-symlink parents, never overwriting. This mode assumes no hostile
concurrent workspace mutation; portable identity rechecks are not atomic against
ancestor swaps. Failed cwd writes truncate owned bytes but may leave an empty
private file that must be removed before retry.
