Local API & Integrations

Claspt includes a local HTTP API server that runs on your machine, allowing external tools to read and write pages and secrets programmatically. It also registers as a Model Context Protocol (MCP) server for AI assistant integration.

Use Cases

• AI assistants — let Claude Desktop or ChatGPT access your notes via MCP.
• Shell scripts — query secrets from the command line during deployments.
• Automation — integrate with tools like Raycast, Alfred, or custom workflows.
• CI/CD — pull secrets locally before running builds (without committing them to code).

Enabling the API

1. Open Settings > Integrations > Local API.
2. Turn it on. The server listens on port 9315 unless you change it.
3. Give each tool its own key: Pair another browser for the extension, claspt mcp install <tool> for an AI tool, or API Clients › New for a script. Keys are shown once and never again.

Note

The API only accepts connections from localhost (127.0.0.1). It is not accessible from other machines on your network.

Access Tokens

Every tool that talks to Claspt has its own token, under its own name, so each one can be revoked without touching the others. Create one in Settings > Integrations > API Clients, or let the tool create its own: claspt mcp install claude-code (also cursor, codex, windsurf, gemini-cli, claude-desktop) writes a fresh token straight into that client’s configuration, and pairing the browser extension does the same for it.

A token is shown once, when it is created. Claspt keeps only a hash of it, so nothing on disk can be turned back into a working token. If you lose one, revoke it and create another.

Scope	Pages and memory	Secret values	Approval
Notes	Read and write	Redacted	Not needed
Secrets	Read and write	Decrypted	Optional popup, per request or per session

• Notes (clsn_…) — pages, search, folders, agent memory. Secret block values are redacted and secret blocks cannot be created or edited. Use this for anything that does not need a credential.
• Secrets (clss_…) — everything Notes can do, plus decrypting secret values, subject to the access mode in Settings. When approval is on, the popup names the client that is asking.

Caution

A Secrets token with approval off can read every secret without prompting. Give one only to a tool you trust, and revoke it from the client list the moment that stops being true.

The routes

Every route is in the API Explorer, generated from the OpenAPI document, with parameters, schemas and a curl example each. The Local API Reference has the rules that apply to all of them: scopes, errors, identifiers, concurrency and approval. A first request:

# Who is asking, and what this build can do
curl http://127.0.0.1:9315/api/status \
  -H "Authorization: Bearer YOUR_KEY"

# Pages in a folder
curl "http://127.0.0.1:9315/api/pages?folder=credentials" \
  -H "Authorization: Bearer YOUR_KEY"

# Full-text search; secret values are never searched or returned
curl "http://127.0.0.1:9315/api/search?q=deploy+production" \
  -H "Authorization: Bearer YOUR_KEY"

With a Secrets key, reading a secret value asks for approval in the app when the access mode is on; the request waits up to 30 seconds for the answer.

MCP Server (AI Integration)

Claspt is an MCP server. Connect a tool with one command:

claspt mcp install claude-code claude-desktop

It writes Claspt into each named client’s config with one shared key for the tools on this machine (--secrets for a key that may read secret values, --separate for a key of a tool’s own, --project for a project-scoped config). claspt mcp doctor shows every config’s key and whether the open vault accepts it. The tools the server offers: memory (read, write, append, search, review), pages and search, find and read secrets, references, the audit, the generator. See AI tools: memory and AI tools: credentials.

How MCP differs from the HTTP API

The MCP server proxies to the same local API with the same key, so scope, approval, the rate limit and the access log apply exactly as they do to any other client. The master password never reaches the tool.

Security Model

• Localhost only — no remote access, no port forwarding.
• Scoped tokens — each token has explicit permissions.
• Approval — a Secrets-scope read asks in the app, naming the client and the page; approvals can be once, until lock, or standing for one client and one page.
• Rate limit — each client may decrypt at most 15 secrets a minute to start.
• Locked vault — requests that need the key are refused while the key lock is on.
• Access log — every request is recorded with the client’s name in Settings > Activity and with claspt log; values are never logged.
• Write guard — a write carrying a recognisable key outside a secret block is refused.