@pi-unipi/mcp

Browse a catalog of 7,800+ MCP servers, add them interactively, and use their tools in Pi. MCP (Model Context Protocol) servers expose external capabilities — GitHub operations, database queries, file system access — as tools the agent can call.

The add command opens a split-pane overlay: server browser on the left, JSON config editor on the right. Pick a server, edit its config, save. Tools from added servers are automatically registered as Pi tools with the pattern {serverName}__{toolName}.

Commands

Command	Description
/unipi:mcp-add	Open browse and editor overlay to add MCP servers
/unipi:mcp-settings	Interactive settings with enable/disable/edit
/unipi:mcp-sync	Force sync server catalog from GitHub
/unipi:mcp-status	Text summary of all configured servers

Setup Flow

1. Run /unipi:mcp-add
2. Browse or search the server catalog
3. Edit the config in the right pane
4. Save and restart Pi to activate

Special Triggers

When MCP is installed, all workflow skills get access to MCP server tools. Tools are named {serverName}__{toolName} — for example, github__search_code or filesystem__read_file.

MCP registers with the info-screen dashboard, showing server count, active servers, and total tools. The footer subscribes to MCP_SERVER_STARTED, MCP_SERVER_STOPPED, and MCP_SERVER_ERROR events to display MCP status.

Agent Tools

MCP tools are registered dynamically based on configured servers. Once a server is added and Pi restarts, its tools become available to the agent.

Example tool calls:

github__search_code({ query: "authentication middleware" })
github__list_pull_requests({ state: "open" })
filesystem__read_file({ path: "/home/user/config.json" })

The agent doesn't need to know about MCP directly — tools appear in its tool list with the server prefix.

Configurables

File Locations

~/.unipi/config/mcp/              ← Global defaults
{project}/.unipi/config/mcp/      ← Project overrides

Files at Each Level

• mcp-config.json — Server definitions (standard MCP format)
• config.json — Metadata (enabled/disabled, sync preferences)
• auth.json — Sensitive environment variables (chmod 600, optional)

Config Format

mcp-config.json uses the standard MCP format compatible with Claude Desktop, Cursor, and other MCP clients:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Config Merge Rules

1. Server exists only in global — loaded normally
2. Server exists only in project — loaded normally
3. Server exists in both — project wins entirely
4. "enabled": false in project metadata — disabled even if defined globally

Troubleshooting

Server won't start: Check /unipi:mcp-status for errors, verify the command exists on your system.

Tools not appearing: Ensure the server is running and supports the MCP protocol.

Config issues: Validate JSON syntax and check file permissions.

Sync issues: Run /unipi:mcp-sync, check network. The seed catalog (49 servers) is available offline as fallback.

License

MIT