@agimon-ai/po-mcp

Domain-aware MCP server selection and access boundaries for Pi sessions composed with Po.

Packages

Package details

extension

Install @agimon-ai/po-mcp from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@agimon-ai/po-mcp
Package
@agimon-ai/po-mcp
Version
0.0.0-alpha.170
Published
Nov 19, 2026
Downloads
31.9K/mo · 7,513/wk
Author
agiflow-ai
License
BUSL-1.1
Types
extension
Size
2.4 MB
Dependencies
15 dependencies · 1 peer

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@agimon-ai/po-mcp

Domain-aware MCP selection, connections and inline Apps for Po. Disallowed stdio servers are removed before their commands start, not merely hidden from the model.

Requires Node.js 24 or newer. Starter configs select this adapter in default.packages; keep it there or move it to a selected layer. Configuration and adapter contracts are alpha.

Configure servers

Repository .mcp.json entries describe direct servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

Your Po home's mcp.json uses the same shape. Home entries load first; repository, plugin or domain entries with the same name take precedence. Selected legacy plugins may supply .mcp.json; Agent Plugin v1 uses mcp.json, validated through the portable contract with private persistent PLUGIN_DATA. Invalid entries are isolated from other entries.

Proxy upstreams come from mcp-config.yaml. Domains select direct mcp.servers and proxy mcp.proxy names in .po/domains.yaml. An absent or empty allowlist retains configured entries. Use po --no-mcp to load none.

Add server in a repository's MCP page writes .mcp.json; Settings > MCP servers writes the home file. A local command needs explicit trust confirmation. Adding never replaces an existing name or rewrites invalid JSON.

Named header/environment secrets can be stored in the vault through the add request's secretFields. The vault is written first and the config stores a ${vault:...} reference; failed config writes remove the newly stored secrets. This operation requires a vault.

Use tools

Read the MCP code-mode guide, then discover the permitted catalog:

// Discover actual server/tool names and schemas before this call.
const result = await mcp.call(serverName, toolName, args);
return result;

Typed members such as mcp.server.tool(args) use the same connections and admission checks. Names are exact configured server and original tool names; use bracket access when needed. Narrow large discovery output with discover({ query }). Never guess signatures.

Results expose text, images, structured content and blocks. image(result) emits returned images. Upstream isError results reject. File parameters sent to another server still require consent, and the wait counts against the exec deadline. After a runtime replacement, use fresh discovery and a new exec; an old run cannot borrow the replacement runtime.

With code mode, the main model's duplicate direct declarations are withdrawn, including MCP App tools. Without it, direct tools remain. Children receive only the MCP subset allowed by their inherited capability ceiling and selectors. The namespace never grants new server access.

Configured names, not downstream-reported names, identify connections. Two entries pointing at the same URL can use different accounts and credential slots. Tool prefixes are not parsed to route calls.

Approval and connection controls

A tool asks before running unless its server declares readOnlyHint: true or destructiveHint: false. This applies to direct tools, mcp_use, typed code-mode members and App calls. mcp.call refuses tools that ask first; use their typed member. Calls queue for replay after approval rather than blocking the agent.

The host's autoApproveDestructiveTools setting in <po home>/mcp-settings.json skips these prompts for all live sessions. /mcp approve on|off|status changes one session until restart. Subagents, background runs and unattended calls cannot answer an ask prompt. These settings do not make an untrusted server safe.

Commands include /mcp, status, auth <server>, disconnect <server>, unauthorize <server>, approve on|off|status and reload. The Context panel shows configured tools, schemas, warnings and authorization state. Authorization requests appear in the panel; a headless host does not automatically open a desktop browser.

Removed, disconnected, signed-out or degraded servers leave the active surface until they reconnect. Explicit disconnect survives reload. On edge, a closed remote connection or 401/403 response removes that server for the remainder of the session.

Credentials and trust

Allowed stdio entries execute with the owning session's admitted environment and OS privileges. Review commands, arguments and configuration as executable code. The adapter uses the workspace-owned @agimon-ai/po-mcp-proxy in process; it does not start the proxy's Hono server.

OAuth credentials are encrypted in po/vault, namespace mcp.oauth, keyed by source scope and configured server name. Repository scope uses the Git common-directory digest: worktrees share it, separate clones do not. URL binding prevents blind replay to another endpoint. Old OS-keyring or ~/.mcp-proxy/oauth credentials are not migrated; authorize again. Without a vault, credentials remain in memory and a diagnostic is shown. Near-expiry tokens refresh before requests; vault leases coordinate rotating-token refresh across processes.

${vault:NAME} works in headers, environment values and bearerToken, not in URLs, commands, arguments or working directories. Names are 1 to 64 letters, digits, dots, underscores or hyphens. References resolve on a connection-time copy, so config, hashes and definition caches retain only the reference. Secrets are bound to an HTTPS origin (or loopback HTTP, without redirects) or to an exact command and argument list. Changing that destination makes the secret unavailable. A repository server cannot read a home-scope secret through this mechanism.

Missing secrets can be supplied through the session's owner-only secret endpoint. Compatibility frontends reading files directly see the unresolved reference. Any trusted in-process plugin can read vault namespaces; this is not package isolation.

The default OAuth callback is http://127.0.0.1:19876/callback. Browser and runtime must share that loopback namespace. A remote browser's own loopback is not the server's.

Temporary and private plugin connections

Trusted session plugins inject the core PO_MCP_SERVICE contract and use readPoMcp on their session Cordis root. register(input, signal) connects immediately and returns an identity-owned handle with name, live snapshot(), validated invoke() and asynchronous idempotent dispose(). It publishes tools into the session, but never rewrites saved config or replaces an existing name.

No-auth HTTP/SSE registrations require explicit-port loopback HTTP. API-key registrations also accept HTTPS, pin credentials to the destination origin, refuse redirects and never start OAuth. Keys can reference the session's admitted environment or be supplied by trusted server code. URL userinfo, fragments, interpolation, reserved names and occupied names are rejected. Keys stay in the session overlay, outside disk caches and the vault. Literal secrets in exec source still persist in scripts and transcripts: do not paste them.

Establishment cancellation rolls back partial registration. Exec completion does not dispose a successful connection. Call dispose() in finally when the work ends; it remains usable after cancellation or selection changes. Provider shutdown retires handles and closes connections, not external server processes. Legacy localServers and sessionServers remain compatibility APIs.

For private upstreams, use the core PO_MCP_CONNECTIONS_CONTRACT. connect() accepts a package owner, public HTTPS Streamable HTTP URL, credential or saved credential ID, fixed appTools, and a plugin lifetime. It does not publish definitions to session tools, discovery, skills, status, saved config or caches. No sign-in or refresh is performed. Saved credentials are encrypted under the owner and origin; disposing retains them, while forgetCredential() explicitly deletes them. Package ownership is not a separate access-control boundary.

Private App results must retain wrapper-tool invocation identity and details; use the shared MCP result card. App interactions require approval once per open App and confirmation for each call, restricted to the fixed allowlist and current App-visible tools. Records are in memory, limited to 256 per connection and unavailable after restart. Edge hosts must supply outbound policy and fetch capabilities.

Help-only test servers

With permission, Help mode's main-agent-only mcpTest namespace can add, list and remove temporary URL servers; without code mode use mcp_test_server. HTTP/SSE support optional headers and OAuth settings. Stdio and /mcp add are unsupported.

Test configuration and credentials stay in memory across MCP reloads, never enter saved config or the vault, and do not transfer to new sessions. They cannot replace configured names or override --no-mcp. Turning Help off hides management tools but does not disconnect test servers. Memory storage does not redact arguments or history; use admitted ${ENV_VAR} references rather than literal secrets.

Inline Apps

Standard MCP Apps and supported ChatGPT widgets render in opaque sandboxed frames, with ordinary text fallback where iframe CSP is unavailable. Every App starts read-only, including replayed history. Enabling interactions creates a fresh connection-bound lease; each tool call and attributed follow-up still needs host confirmation. Visibility is not consent.

Reopening reads retained results/state without rerunning the original tool. Private metadata and bounded widget state stay outside model content. Apps receive live light/dark theme state. ChatGPT support includes input/output globals, calls, state, follow-ups, inline display, height, close and confirmed external links, but not file libraries, checkout, accounts, modal/fullscreen, stable origins, sampling or automatic context updates.

An App called from exec remains attached to that call's card and survives session replay. Background exec and private-connection results do not show an App. Retained App results and model-facing output have separate bounds.

Remote file transfer

Session MCP exposes share_file and save_file subject to connection grants. share_file({path}) uses session-bound sharing without a consent prompt. It requires remote access; its bearer links expire after ten minutes and allow at most three downloads. Outbound file parameters to other servers still need consent.

save_file accepts one HTTPS-download or base64 form. HTTPS uses public-address checks, pinned DNS, at most three revalidated redirects, a 30-second deadline and a 25 MiB cap. Base64 is validated before decoding and capped at 5 MiB. Without a destination it creates a private session attachment. An optional destination is cwd-relative, needs existing non-symlink parents and is created exclusively, never overwritten. MIME hints are not trusted as detection.

Containment uses realpath rechecks, not atomic descriptor-relative operations. It assumes no hostile concurrent workspace mutation: ancestor swaps may expose bytes or create a file outside cwd before rejection. Failed cwd writes truncate their created descriptor but can leave an empty private file. Cleanup does not unlink mutable paths; inspect and remove an empty artifact before retrying that destination.

Development

pnpm exec nx run-many -t lint typecheck build test -p @agimon-ai/po-mcp

Inline App integration also has CLI-owned Playwright and app-system tests. po --emit-mcp <directory> emits resolved configuration without launching a model; it is not a promise that inspecting MCP commands has no side effects.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.