Feature: project MCP declarations to Pi via pi-mcp-adapter

[tekumara]

Feature: project MCP declarations to Pi via pi-mcp-adapter

dotagents mcp add currently projects declarations into native MCP configuration for Claude, Cursor, Codex, Copilot, VS Code, and OpenCode, but not Pi.

Please add a pi MCP projection compatible with pi-mcp-adapter.

Motivation

Pi users who install pi-mcp-adapter can use MCP servers lazily, avoiding loading every server tool definition into the initial context. They should be able to declare an MCP server once through dotagents and have it available to Pi when pi is selected as an agent target.

For example:

npx @sentry/dotagents mcp add github \
  --command "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN

Proposed projection

When agents.toml includes pi, project dotagents-managed MCP declarations to pi-mcp-adapter’s shared configuration layer:

Scope	Target file
Global	~/.config/mcp/mcp.json
Project	.mcp.json

Emit the mcpServers JSON object format consumed by pi-mcp-adapter, supporting both stdio (command / args / env) and Streamable HTTP (url / headers) declarations.

Why use the shared layer rather than Pi’s override layer?

pi-mcp-adapter merges configuration sources in precedence order. The shared files above supply the base server definitions; Pi-specific files are loaded later and override individual fields:

Shared base	Higher-precedence Pi override
~/.config/mcp/mcp.json	~/.pi/agent/mcp.json
.mcp.json	.pi/mcp.json

This is the right split for dotagents. Dotagents should write the portable/base declaration, while Pi retains its conventional override files for adapter-specific settings and local state. For example, a user can set only { "disabled": true } for a server in a Pi override file; the adapter retains the command, arguments, and environment setup from the dotagents-generated shared declaration while disabling that server for Pi.

Writing directly to ~/.pi/agent/mcp.json or .pi/mcp.json would make dotagents compete with Pi’s higher-precedence override layer and risks clobbering or managing adapter-specific settings such as enable/disable state.

Desired behaviour

• Only write the Pi projection when pi is listed in agents.toml.
• Preserve unrelated top-level configuration and unmanaged MCP servers in an existing target file.
• Track generated server entries so dotagents mcp remove <name> removes only the corresponding dotagents-managed entry.
• Make install and sync idempotently reconcile the generated Pi entries.
• Use the environment-variable reference syntax supported by pi-mcp-adapter; never serialize secret values from the shell into configuration.
• Respect Pi project-trust expectations when documenting or implementing project-local output.

Acceptance criteria

1. A stdio declaration made with dotagents mcp add is available through pi-mcp-adapter when agents = ["pi"] is configured.
2. Streamable HTTP declarations, headers, and environment variables are projected correctly.
3. Global scope writes ~/.config/mcp/mcp.json; project scope writes .mcp.json.
4. A Pi override in ~/.pi/agent/mcp.json or .pi/mcp.json can override a dotagents-projected shared server without duplicating its base definition.
5. Existing unmanaged shared configuration is preserved.
6. mcp remove, install, and sync reconcile only dotagents-managed Pi entries.
7. Tests cover creation, merge/preservation, removal, precedence with Pi overrides, and idempotency for both scopes.

References

• pi-mcp-adapter configuration layout and precedence
• dotagents MCP CLI documentation