@toknbase/mcp-server

Zero-knowledge secrets management for AI agents via the Model Context Protocol.

Toknbase is the only secrets manager where the host never sees your plaintext secrets. This MCP server connects your AI coding assistant to your Toknbase vault -- read, create, update, rotate, and delete secrets directly from Cursor, Windsurf, Claude Code, VS Code, Zed, and Cline.

Quick Start

1. Create an Agent Token

Log in to your Toknbase dashboard and navigate to AI Agents. Create a new token with the scope you need:

• read_only -- list and retrieve secrets
• read_write -- list, retrieve, create, update, rotate, and delete secrets
• full_access -- all of the above plus folder creation and assignment

Copy the agt_ token value -- it is shown only once.

2. Add to Your Editor

Replace agt_your_token_here with your token. The canister ID is pre-configured and does not need to be set manually.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here"
      }
    }
  }
}
Claude Code (run in terminal)

claude mcp add toknbase -- npx -y @toknbase/[email protected]
export TOKNBASE_AGENT_TOKEN=agt_your_token_here
Windsurf / VS Code / Cline (mcp.json)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here"
      }
    }
  }
}
3. Test From Terminal
TOKNBASE_AGENT_TOKEN=agt_your_token_here npx @toknbase/[email protected]
You should see:

[toknbase-mcp] Server running. Canister: xi7mc-uaaaa-aaaan-q5raa-cai
Press Ctrl+C to stop.

Available Tools (14 total)
Tool	Description	Required Scope
toknbase_list_secrets	List all secrets (names, descriptions, environments -- no plaintext values)	read_only
toknbase_get_secret	Retrieve a secret by name including its value	read_only
toknbase_search_secrets	Search secrets by name or environment filter	read_only
toknbase_create_secret	Add a new secret to the vault	read_write
toknbase_update_secret	Update a secret's value	read_write
toknbase_delete_secret	Permanently delete a secret	read_write
toknbase_rotate_secret	Rotate a secret and save the previous value to version history	read_write
toknbase_batch_create_secrets	Create up to 20 secrets in a single call	read_write
toknbase_get_audit_log	Retrieve a paginated audit log (max 100 entries per page)	read_only
toknbase_list_team_secrets	List secrets belonging to a team you are a member of	read_only
toknbase_create_folder	Create a new folder	full_access
toknbase_list_folders	List all folders	read_only
toknbase_assign_folder	Assign a secret to a folder	full_access
toknbase_get_token_info	Get the current token's name, scope, and folder restriction	read_only
Environment Variables
Variable	Required	Description
TOKNBASE_AGENT_TOKEN	Yes	Your agt_ agent token from the dashboard
TOKNBASE_CANISTER_ID	No	Override the canister ID (default: xi7mc-uaaaa-aaaan-q5raa-cai)
TOKNBASE_IC_HOST	No	Override the IC host (default: https://icp-api.io)
Security
Toknbase is zero-knowledge -- your plaintext secrets never leave your device. The MCP server communicates with the Toknbase canister on the Internet Computer, which stores only encrypted values. Decryption happens client-side in your browser using your personal key.

Every action taken by an agent token is recorded in your Toknbase cryptographic audit log under the token's name and is visible in the dashboard.

Troubleshooting
"Missing TOKNBASE_AGENT_TOKEN"
You forgot to set the env var. Add it to your editor's MCP config under env.

"Canister has no update method"
You are running an old cached version. Clear the cache and re-run with the pinned version:

rm -rf ~/.npm/_npx
npx @toknbase/[email protected]
Canister takes 30-60 seconds to respond on first call
Normal behaviour after a long idle period. The canister is warming up. Subsequent calls are fast.

Requirements
Node.js 18+
A Toknbase account with an active agent token (sign up free)