MCP trong Pi Agent Platform
Pi core không hard-code MCP. Platform cài pi-mcp-adapter để dùng MCP theo kiểu token-efficient, và thêm một lớp quản lý server lên trên bốn layer config.
Bắt đầu ở đâu
Gõ /piagent-mcp là ra menu — không cần nhớ subcommand nào:
MCP
Servers — 2/3 ready
Doctor — 1 need attention (recommended)
Inspect a server
Approve a repository server — 1 waiting
Turn a server off
Add a server
All subcommandsMenu dựng theo đúng thứ project đang có: chưa server nào bị tắt thì không hiện "turn back on", không server nào chờ duyệt thì không hiện "approve". Chọn việc cần server thì nó hỏi tiếp server nào — trừ khi chỉ có đúng một lựa chọn.
Mọi mục trong menu đều gõ thẳng được:
/piagent-mcp doctor cái nào chưa chạy được và còn thiếu gì
/piagent-mcp status bảng đầy đủ
/mcp trạng thái kết nối live, do adapter giữ
/mcp-auth <name> đăng nhập OAuth cho một serverNgoài terminal thì cùng bộ lệnh đó bỏ dấu /: piagent-mcp list, piagent-mcp doctor. Thêm và xoá server chỉ có ở terminal. Chi tiết ở Quản lý server.
Ba thứ trùng tên, không nối với nhau
Đây là chỗ gây nhầm nhiều nhất. Không có dòng code nào map capability name sang MCP server id — khai "github" trong mcpCapabilities không bật server MCP tên github, và ngược lại.
| Thứ | Ở đâu | Là gì |
|---|---|---|
| mcpCapabilities: ["github"] | .pi/piagent-profile.json | Nhãn capability cho tool registry |
| toolCapabilities | base-policy.json | Map một tool tên là github sang capability |
| server github | ~/.config/mcp/mcp.json | Server MCP thật, chạy qua Docker |
Bốn layer config
Cả bốn file đều được đọc. --scope của piagent-mcp chính là bốn tên này.
| Scope | File | Dùng khi nào |
|---|---|---|
| global | ~/.config/mcp/mcp.json | Mặc định. Dùng chung cho nhiều agent và nhiều project |
| pi-global | ~/.pi/agent/mcp.json | Chỉ khi cần override riêng cho Pi |
| project | .mcp.json | Server đặc thù repo, commit được |
| pi-project | .pi/mcp.json | Override riêng Pi trong một repo |
Clone một repo về là mang theo cả .mcp.json của nó. Vì vậy server ở hai scope đó phải qua approval gate trước khi dùng được.
Preset seed sẵn
piagent-setup và piagent-install đều cài pi-mcp-adapter và seed preset core mặc định. Bỏ qua bằng --no-mcp.
| Preset | Server | Mục đích |
|---|---|---|
| minimal | — | Chỉ seed settings an toàn |
| docs | Context7 | Docs mới của framework/library |
| browser | Chrome DevTools, Playwright | Inspect UI/runtime, browser automation |
| github | GitHub MCP | Issue/PR/repo/release workflow |
| design | Figma remote | Design-to-code qua Figma OAuth |
| design-local | Figma desktop | Dev Mode MCP chạy local |
| web | Context7, Chrome DevTools, Playwright | FE/web workflow |
| core | Context7, Chrome DevTools, GitHub | Baseline mặc định của team |
| popular | core + Playwright + Figma | Baseline nhiều team dev dùng |
| all | popular + Figma desktop | Đầy đủ |
Mọi server đều pin theo version hoặc digest. MCP server là code chạy trên máy operator với credential của operator, nên tag trôi nổi sẽ biến mỗi session thành một quyết định supply-chain không ai có mặt để duyệt.
Server connect lazy — không có gì được kiểm tra cho tới lần gọi đầu tiên. Trạng thái auth cho biết server nào thật sự sẵn sàng.
Token efficiency
pi-mcp-adapter đưa mọi server qua một proxy tool duy nhất tên mcp, thay vì nạp toàn bộ tool schema vào context lúc start. Mặc định directTools: false, cộng với outputGuard và idleTimeout.
Proxy tool tên mcp không nằm trong alwaysAllowedTools và không có trong toolCapabilities, nên enforce sẽ chặn toàn bộ MCP. Khai thêm mcpCapabilities không cứu được vì block xảy ra trước khi capability được đọc. Ngoại lệ duy nhất là permission profile trusted-full-access.