@toknbase/mcp-server

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

Toknbase is the first secrets manager with a native MCP server. This package 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. The canister never sees your plaintext secrets; values are decrypted by the MCP server using your agent token as the key before being returned to the AI agent.

Quick Start

1. Create an Agent Token

Log in to your Toknbase dashboard and navigate to Settings → Agent Tokens. Create a new token with the scope you need:

• read_only — list and retrieve secrets
• read_write — list, retrieve, create, and update secrets
• full_access — all of the above plus delete, rotate, and folder management

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

2. Enable Agent Access on Your Secrets

For each secret you want the AI agent to be able to read, open the secret card in the dashboard and toggle "Enable MCP agent access". This encrypts a copy of the value specifically for your agent token. Secrets without this toggle enabled will return a helpful error message to the agent.

3. Add to Your Editor

The production canister ID is pre-filled. Replace agt_your_token_here with your agent token.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
        "TOKNBASE_CANISTER_ID": "xi7mc-uaaaa-aaaan-q5raa-cai"
      }
    }
  }
}

Claude Code (~/.claude.json, mcpServers section)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
        "TOKNBASE_CANISTER_ID": "xi7mc-uaaaa-aaaan-q5raa-cai"
      }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
        "TOKNBASE_CANISTER_ID": "xi7mc-uaaaa-aaaan-q5raa-cai"
      }
    }
  }
}

VS Code (.vscode/mcp.json in your project)

{
  "servers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
        "TOKNBASE_CANISTER_ID": "xi7mc-uaaaa-aaaan-q5raa-cai"
      }
    }
  }
}

Cline (MCP Servers panel in the Cline sidebar)

{
  "mcpServers": {
    "toknbase": {
      "command": "npx",
      "args": ["-y", "@toknbase/[email protected]"],
      "env": {
        "TOKNBASE_AGENT_TOKEN": "agt_your_token_here",
        "TOKNBASE_CANISTER_ID": "xi7mc-uaaaa-aaaan-q5raa-cai"
      }
    }
  }
}

Available Tools (15)

| Tool | Description | Required Scope | |---|---|---| | toknbase_list_secrets | List all secrets (names, descriptions, environments — no values) | read_only | | toknbase_get_secret | Retrieve the plaintext value of a specific secret by name | read_only | | toknbase_get_secret_by_environment | Retrieve a secret filtered by environment tag (development, staging, production) | read_only | | toknbase_search_secrets | Search secrets by name or description | 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_rotate_secret | Rotate a secret to a new value | read_write | | toknbase_batch_create_secrets | Create multiple secrets at once | read_write | | toknbase_delete_secret | Permanently delete a secret | full_access | | toknbase_list_folders | List all folders | read_only | | toknbase_create_folder | Create a new folder | read_write | | toknbase_assign_folder | Assign a secret to a folder | full_access | | toknbase_get_audit_log | Retrieve the audit log (paginated) | read_only | | toknbase_list_team_secrets | List secrets for a specific team | read_only | | toknbase_get_token_info | Get metadata and scope for the current agent token | read_only |

Note: toknbase_batch_create_secrets stores values using the standard secret path. To make batch-created secrets readable via toknbase_get_secret, open each secret in the dashboard and toggle "Enable MCP agent access" after creation.

Environment Variables

| Variable | Required | Description | |---|---|---| | TOKNBASE_AGENT_TOKEN | Yes | Your agt_ agent token from the dashboard | | TOKNBASE_CANISTER_ID | Yes | Your Toknbase canister ID (production: xi7mc-uaaaa-aaaan-q5raa-cai) |

Security

Toknbase uses a dual-storage model to preserve zero-knowledge guarantees even for agent-accessible secrets:

• At rest in the canister: All values are stored as ciphertext. The canister never holds plaintext.
• For agent reads: When you enable MCP agent access on a secret, the value is encrypted in your browser using your agent token as the key. The MCP server decrypts it server-side when the agent requests it, then returns the plaintext to the AI agent.
• Audit trail: Every action taken by an agent token is recorded in your Toknbase cryptographic audit log under the token's name.

Token Rotation Warning

If you revoke or rotate an agent token, any secrets encrypted for that token become unreadable via MCP. After creating a new token, re-enable MCP agent access on each affected secret in the dashboard to re-encrypt with the new token.

Requirements

• Node.js 18+
• A Toknbase account with an active agent token (sign up free at toknbase.net)