Đăng nhập và trạng thái sẵn sàng

Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được.

Platform không giữ token

Token MCP đã có chỗ ở: luồng OAuth thuộc về pi-mcp-adapter — chính nó đăng ký /mcp và /mcp-auth, và chính nó lưu, refresh, thu hồi. Dựng thêm một kho credential nữa để giữ credential của bên thứ ba chỉ tạo thêm một chỗ để token rò ra. Việc của platform vì vậy là phát hiện và chỉ đường.

/mcp-auth figma

Ranh giới

Platform không chạy OAuth, không lưu token, không refresh. Nó biết một server cần đăng nhập, nhưng không biết phiên đăng nhập còn hạn hay không — và nó nói đúng như vậy thay vì đoán.

Secret bị từ chối ngay khi ghi config

MCP config được nhiều client đọc, nằm trong home hoặc trong repo, và ở scope project thì được commit. Một token gõ vào --env sẽ đi tới tất cả những chỗ đó. Nên add từ chối, và nói luôn dạng cần dùng:

$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
written into MCP config. Export it in your shell and reference it instead:
--env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'

Theo tên field

Tên chứa token, secret, password, api_key, authorization… thì giá trị bắt buộc phải là tham chiếu biến môi trường.

Theo giá trị

Tên không nói gì thì giá trị vẫn được đọc riêng, nên --env CONFIG=ghp_... cũng bị bắt.

Áp dụng cho cả --header. --url chỉ nhận https, hoặc http khi host là loopback — Figma desktop MCP đúng là trường hợp đó. list và get mask giá trị nhưng in nguyên ${VAR}, vì đó là tên biến chứ không phải nội dung.

Trạng thái sẵn sàng

Đếm số server không nói được server nào trả lời được. /piagent-mcp doctor phân loại từng cái:

State	Nghĩa	Cách xử lý
ready	Đủ điều kiện, gọi được	—
needs-env	Config tham chiếu ${VAR} mà biến chưa export	Export biến trong shell profile
needs-command	Executable không có trên PATH	Cài, hoặc sửa lại server
pending-approval	Repo khai server này, chưa ai duyệt trên máy này	/piagent-mcp approve <name>
approval-changed	Đã duyệt nhưng định nghĩa đã đổi	Đọc lại rồi duyệt lại
rejected	Đã từ chối cho project này	reset nếu đổi ý
disabled	Tắt bằng disable	/piagent-mcp enable <name>
oauth	Đăng nhập do Pi giữ	/mcp-auth <name> nếu chưa login

Chỉ báo cái biết chắc. needs-env in ra tên biến, không bao giờ in giá trị.

Trong session là /piagent-mcp doctor — cùng báo cáo, và remedy in ra dạng slash command vì đó là thứ chạy được ngay tại chỗ. Ngoài terminal:

$ piagent-mcp doctor
OK   context7 (global): ready
OK   chrome-devtools (global): ready
NEED github (global): GITHUB_PERSONAL_ACCESS_TOKEN is referenced but not set
       -> export GITHUB_PERSONAL_ACCESS_TOKEN=... in your shell profile
NEED docker: installed but the daemon is not responding
       -> start Docker Desktop, then re-run piagent-mcp doctor

Vì sao oauth không phải lỗi

Nó không xuất hiện trong notice đầu session. Platform không phân biệt được đã login hay chưa, nên báo mỗi session sẽ thành nhiễu và hết được đọc. Notice chỉ nêu những state chặn chắc chắn; tắt bằng PIAGENT_NO_MCP_NOTICE=1.

doctor chạy thêm docker info — chậm, nên chỉ có ở doctor chứ không ở session start. piagent-doctor cũng đưa các state chặn vào warnings.