Authentication and readiness
The platform does not store tokens or run OAuth. It rejects secrets in configuration and reports which servers are actually ready.
The platform does not store tokens
MCP tokens already have an owner: OAuth belongs to pi-mcp-adapter. The adapter registers /mcp and /mcp-auth and owns storage, refresh, and revocation. A second credential store would only create another leak surface. The platform therefore detects and guides.
/mcp-auth figmaThe platform does not execute OAuth, store tokens, or refresh them. It can identify that a server requires authentication, but cannot prove whether an existing login is still valid, and reports that uncertainty explicitly.
Secrets are rejected before configuration is written
MCP configuration may be read by several clients, lives in a home directory or repository, and project scope may be committed. A token supplied through --env would propagate to all those locations. The add command rejects it and shows the safe form:
$ 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}'Field-name detection
Names containing token, secret, password, api_key, or authorization require environment-variable references.
Value-shape detection
Values are checked independently, so a neutral name such as --env CONFIG=ghp_... is also rejected.
The same rules apply to --header. --url accepts HTTPS, or HTTP only for loopback hosts such as Figma desktop MCP. list and get mask values while preserving ${VAR}, because the variable name is not the credential.
Readiness states
A server count cannot show which server can answer a call. /piagent-mcp doctor classifies each server:
| State | Meaning | Action |
|---|---|---|
| ready | Requirements are satisfied | — |
| needs-env | Configuration references an unset ${VAR} | Export the variable in the shell profile |
| needs-command | The executable is missing from PATH | Install it or update the server definition |
| pending-approval | The repository supplied this server and the machine has not approved it | /piagent-mcp approve <name> |
| approval-changed | An approved definition changed | Review and approve again |
| rejected | The project server was rejected | Use reset to reconsider |
| disabled | Disabled explicitly | /piagent-mcp enable <name> |
| oauth | Authentication is owned by Pi | /mcp-auth <name> when login is needed |
The report states only what it can prove. needs-env prints the variable name, never its value.
Inside a session, /piagent-mcp doctor returns the same report with slash-command remedies. From a 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 doctorIt does not appear in the session-start notice because the platform cannot tell whether the user is already logged in. Repeating an uncertain warning every session would create noise. The notice includes only proven blockers; disable it with PIAGENT_NO_MCP_NOTICE=1.
doctor also runs docker info. That slower check belongs in doctor, not session startup. piagent-doctor includes blocking states in its warnings.