Security
Write tokens
Write tokens authenticate agents that need to create, update, or manage MiraDock content through MCP.
Overview
A MiraDock write token is a bearer credential for MCP clients such as Claude Code, Cursor, Codex CLI, and token-based desktop setups. The backend stores a hash of the token, keeps a short display prefix for identification, and records last-used timestamps when a token is accepted.
| Property | Shipped behavior |
|---|---|
| Current prefix | miradock_mcp_ by default |
| Secret length | 32 random bytes encoded as 64 hex characters after the prefix |
| Displayed prefix | The app shows only the prefix plus the first 8 secret characters |
| Scope note | Generated tokens are labeled All workspaces |
Generating tokens
Generate write tokens from /app/mcp. Choose a label that names the client or device, then copy the token immediately. MiraDock only shows the full secret once.
Token scope
Write tokens are not scoped to one workspace in the current product. They authenticate as your MiraDock user with write scope and the generated scope note is All workspaces. That lets the MCP server run write tools for workspaces your account can edit, subject to normal ownership, collaborator, billing, and rate-limit checks.
A write token is required for MCP write tools. Read-only MCP tokens cannot call write tools, and anonymous requests cannot write.
Rotation
- Create a new write token in /app/mcp.
- Update the agent or MCP client configuration with the new token.
- Confirm the client can list or write to the expected workspace.
- Revoke the old token once the new one is working.
Revocation
Revoke tokens from /app/mcp. Revocation sets a revoked timestamp on the credential, and future requests using that token are rejected. Agents using the token lose access immediately.
What to do if a token leaks
- Go to /app/mcp and revoke the leaked token.
- Generate a replacement token for the affected client.
- Update the client configuration outside of chat or shared docs.
- Review recent MCP activity for unexpected writes.
Legacy formats
The backend still accepts a small set of historical token prefixes for existing clients. New tokens use the current MiraDock prefix unless the deployment overrides it with configuration.