MCP tokens and agent permissions
Understand project, user, and owner tokens, their permissions, expiry, revocation, and where Stagekeeper stores records.
Three kinds of token
| Token | Scope | Used for |
|---|---|---|
hs_ Project | One project | Agent connection |
hu_ User | Repositories you own | Agent connections from one shell |
ho_ Owner | You and the project where it was created | Gate approvals from your own session |
Project and user tokens connect to /api/mcp. A user token still has the agent toolset: it cannot open gates. The plugin supplies the project from harness.json on each request, and the server checks that you own it.
Owner tokens use the separate /api/mcp/owner connection. The endpoints do not accept each other's token kinds. Create owner tokens in the project's Tokens tab on Pro or Max.
Keep approval permissions separate
The agent connection has no gate approval or pipeline settings tool. An owner connection can open the gate the item is waiting at; the server rechecks ownership, project availability, plan, and the gate's current entry.
Keep the owner token in your own main session and out of independent agent sessions. It does not grant the web's other actions: send back, hold, reopen, discard, backlog editing, and token management remain on the web.
Save, expire, and revoke
Stagekeeper stores a hash of a token, not its original value. The value is shown once when created. Save it in secure storage and follow the token screen's shell instructions. Do not paste the value into a chat or commit it to the repository.
All three kinds can have an expiry, or no expiry. Restarting a terminal does not expire a token; losing a shell variable does not revoke it. Reuse the same saved value while it is active.
Revoke an individual token when it is no longer needed. Expired or revoked tokens are refused on subsequent authentication. Their old records stay in the history; ending a token does not erase the work it recorded.
State here, files in your repository
Stagekeeper keeps pipeline state, approvals, and references to plans and reports. Your code, plans, and reports stay committed in your Git repository.
Your Claude Code session runs the agents. Stagekeeper coordinates their next step and records the evidence; it does not run your agents for you. Connect your repository or read how automation continues.