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. Toggle Enable.
3. Claspt starts the API server on a random available port (or configure a fixed port).
4. Copy the generated access token.

Note

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

Access Tokens

When you enable the API, you create scoped tokens that control what external tools can do:

Token Type	Pages (Read/Write)	Secrets (Read)	Approval Required
Full Access	Yes	Yes	No
Notes Only	Yes	No	N/A
Secrets Only	No	Yes	Per-request

• Full Access — read and write pages, read secrets. Use for trusted tools you control.
• Notes Only — read and write pages, no access to secret block values. Good for note-taking integrations.
• Secrets Only — read secret values, but every request triggers an approval popup in Claspt. Use for scripts that occasionally need a credential.

Caution

Full Access tokens can read all your secrets without prompting. Only use them with tools you trust completely. Rotate tokens regularly via Settings > Integrations > Manage Tokens.

API Endpoints

All endpoints require the Authorization: Bearer <token> header.

Pages

# List all pages
curl http://localhost:PORT/pages \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a specific page (includes content and metadata)
curl http://localhost:PORT/pages/PAGE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create or update a page
curl -X POST http://localhost:PORT/pages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy Notes", "folder": "credentials", "content": "# Deploy\n\nNotes here."}'

Secrets

# Read secrets from a page (requires Secrets Only or Full Access token)
curl http://localhost:PORT/pages/PAGE_ID/secrets \
  -H "Authorization: Bearer YOUR_TOKEN"

With a Secrets Only token, this request triggers an approval popup in Claspt. You must click Approve in the app before the response is returned.

Search

# Full-text search across the vault
curl -X POST http://localhost:PORT/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "deploy production"}'

Tip

Search results never include secret block values, regardless of token scope. Only page titles, content snippets, and secret labels are returned.

MCP Server (AI Integration)

Claspt registers as a Model Context Protocol server, allowing AI tools like Claude Desktop to access your vault as a context source.

Setup with Claude Desktop

1. Enable the Local API in Claspt.
2. In Claude Desktop, go to Settings > MCP Servers > Add.
3. Select Claspt from the discovered servers (or enter the port manually).
4. Choose a token scope.

Once connected, you can ask Claude questions like “What API keys do I have in my credentials folder?” and it will query your vault via MCP.

How MCP Differs from the HTTP API

The MCP server wraps the same HTTP API but uses the MCP protocol for structured tool calls. AI assistants can discover available actions (list pages, search, read secrets) automatically without you writing curl commands.

Security Model

• Localhost only — no remote access, no port forwarding.
• Scoped tokens — each token has explicit permissions.
• Approval popups — Secrets Only tokens require in-app confirmation for every secret read.
• Vault must be unlocked — all API requests return 401 if the vault is locked.
• Audit log — all API access is logged in Settings > Integrations > API Log.