mcp
API Keys & Security
How Clarity protects your projects and data when using MCP.
How API keys work
When you create an API key in Settings → MCP / API, Clarity:
- 1Generates 32 cryptographically random bytes using Node.js
crypto.randomBytes - 2Encodes them as a base64url string with the prefix
sk_clarity_ - 3Computes a SHA-256 hash of the full key
- 4Stores only the hash in the database
- 5Returns the plaintext key to you exactly once
The plaintext key is never stored, logged, or transmitted after creation. If you lose it, you must generate a new one.
Authentication flow
Every MCP API request follows this path:
- 1Your AI client sends the plaintext key in the
Authorization: Bearerheader - 2The Clarity API hashes the incoming key with SHA-256
- 3It compares the hash against all active key hashes using timing-safe comparison (
crypto.timingSafeEqual) - 4On match, it extracts the associated
user_idand proceeds - 5Every subsequent operation verifies the user owns the requested resource
Timing-safe comparison prevents attackers from learning anything about your key by measuring response times. Every comparison takes the same amount of time regardless of how many characters match.
Ownership verification
API key authentication is only the first layer. Every endpoint also checks resource ownership:
| Endpoint | Ownership check |
|---|---|
| List projects | Filters to projects where user_id matches |
| List / create files | Verifies the project belongs to the user |
| Read / write / delete file | Verifies the file belongs to the user |
| Compile / debug | Verifies the project belongs to the user |
This means even if two users somehow had the same API key hash (impossible due to uniqueness constraints), they could never access each other's data.
Key management best practices
- Use descriptive labels — name keys after the client ("Claude Desktop", "Cursor laptop") so you know what to revoke if compromised
- One key per client — don't reuse the same key across multiple machines or tools
- Disable before deleting — if you suspect a key is compromised, toggle it off immediately via the switch in Settings, then investigate
- Rotate periodically — generate a new key and revoke the old one every few months
- Never commit keys — add your MCP config to
.gitignoreif it contains plaintext keys
Key limits
| Feature | Limit |
|---|---|
| Keys per user | 5 |
| Key length | 48 characters (32 random bytes + prefix) |
| Revocation | Immediate — takes effect on the next API request |
What MCP can and cannot do
MCP can:
- List all your projects and browse file trees
- Read, write, create, and delete files within projects
- Compile LaTeX and Typst documents
- Debug compilation errors with structured analysis
- Search built-in Typst documentation (language features + Touying framework)
- Read full Typst documentation pages
- Generate TikZ illustrations and diagrams
MCP cannot:
- Create or delete entire projects (only files within them)
- Delete the main entry file of a project
- Delete non-empty folders (contents must be removed first)
- Rename or move files between folders
- Upload binary files (images, PDFs, fonts)
- Access other users' data or projects
- Modify account settings, profile, or preferences
- Access billing, payment, or subscription information
- Share or publish projects
- Manage collaborators or permissions
- Bypass ownership verification
Audit trail
Every time your API key is used, Clarity updates the Last used timestamp visible in Settings → MCP / API. This helps you:
- Confirm your MCP connection is active
- Identify stale keys that haven't been used recently
- Detect unexpected usage patterns