Skip to main content
Glama
Sign In
handshake-mcp

handshake-mcp

by zeroai-tech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Handshake

An encrypted credential vault with a small, local setup interface and a CLI for trusted tools. Built by ZeroAI Technologies.

Start

curl -fsSL https://raw.githubusercontent.com/zeroai-tech/handshake/main/install.sh | bash
handshake gui

The interface opens in your browser, served only on this device. It guides you through local or cloud storage, a passphrase, an optional separate security key file (recommended), authenticator enrollment, recovery shares, and selected tool connections. No analytics or external UI assets are loaded. Use Quit Handshake to stop the local server and end its session.

On macOS the installer creates ~/Applications/Handshake.app for double-click launching. From a checkout, run python scripts/create-launcher.py to create it.

Existing vaults open locked. Changing an existing vault's passphrase upgrades its key envelope without rewriting credentials, and preserves its original recovery shares. Opening the interface alone does not migrate your vault.

Related MCP server: keymaster-mcp

Protection and recovery

Use a long, unique passphrase. For protection against someone who knows that passphrase and obtains a database copy, enable the separate security key file and keep it on another device or USB drive, with a separate backup. Keeping it beside the database weakens this protection.

The authenticator code verifies the application's unlock flow. It is not an independent encryption factor: someone with a password-only vault and its passphrase can decrypt the data outside the application. A separate key file adds independent random material to the encryption key.

Save the three recovery shares in separate safe locations. Any two grant full vault access, bypassing the passphrase, authenticator, and key file. Never give them to an AI assistant. Recovery shares rebuild a key; they cannot rebuild a deleted database. Keep an encrypted database export off-device too. Recovery cards for remote storage also contain its connection settings and must be treated as sensitive.

The interface supports storing credentials, listing names, locking, encrypted backups, password changes, recovery, access history, and optional agent connections. Credential values do not appear in the list.

CLI

handshake keyfile --out /path/on/separate-device/handshake-key.json
handshake init --key-file /path/on/separate-device/handshake-key.json
handshake unlock --key-file /path/on/separate-device/handshake-key.json
handshake put work/openai --value -       # provide the value on stdin
handshake list
handshake run -e OPENAI_API_KEY=work/openai -- your-command
handshake export --out encrypted-backup.json
handshake passwd --key-file /path/on/separate-device/handshake-key.json
handshake lock
handshake --help

Unlock produces a bearer session token. Follow the command's instructions to set HANDSHAKE_SESSION in your shell. An authorized token grants access to the whole vault; give it only to trusted tools. The MCP bridge has no unlock tool, passes tokens through subprocess environment variables, and supplies new credential values on stdin rather than command-line arguments. It requires Node.js.

Use handshake agents to register CLI integrations, or choose individual integrations in the interface. Supported integrations include Claude Code, Codex, Gemini CLI, Cursor and Windsurf. Registration alone does not unlock a vault.

Storage

SQLite works without an account. Cloudflare D1, Supabase and Postgres are also supported. Storage credentials are saved locally with restrictive permissions; they grant database access and should be protected. Supabase requires the repository's setup SQL. Postgres requires the optional dependency:

python -m pip install '.[postgres]'

Use handshake setup --help for terminal storage configuration. Remote storage contains encrypted credential values, but names, notes, categories and access logs are visible to its operator. Encryption does not prevent deletion or modification of the database.

Threat model

Situation

Limit or protection

Database or encrypted backup stolen

Values are encrypted; guessing the passphrase remains possible. Separate key-file mode additionally needs that file.

Passphrase and password-only database stolen

The phone-code check cannot prevent offline decryption.

Two recovery shares stolen

Full vault access, given the database.

Token deliberately given to a tool

Whole-vault access for normal application calls until expiry or lock.

A process running as your user

Can inspect local files, process memory and environment, or alter application code. Handshake is not a security boundary against it.

Tool retains a credential or key

Locking cannot revoke material already copied or invalidate a provider's API key. Rotate that credential at its provider.

Network changes

Best-effort public-IP binding rejects detected changes. Lookup failures do not lock you out. This is not strong identity verification.

Storage deleted

Restore an encrypted database backup; recovery shares alone are insufficient.

The session timer governs cooperative application access. The session file and bearer token together can expose the master key to a same-user process. Do not describe the timer or authenticator as protection against a malicious local agent. Audit logs are best-effort and can be altered by someone controlling storage.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python tests/test_vault.py
.venv/bin/python tests/test_hardening.py
.venv/bin/python tests/test_gui.py
.venv/bin/python tests/e2e.py
node tests/verify_gui.cjs /absolute/path/to/playwright

Browser tests use an isolated temporary vault and disable keychain changes. See SECURITY.md for cryptographic details and reporting. This project has not undergone an independent security audit.

Available Tools

5 tools
handshake_getA

Read ONE credential by name. Requires an open session token. Every read is written to an append-only audit log with the reason given, so always pass a truthful reason.

Inputs: name (required), reason (required), session (required).

handshake_listA

List the NAMES of stored credentials (never values). Requires an open session token.

Inputs: session (required).

handshake_logC

Recent access log — who read which credential, when, from where.

Inputs: session (required), limit.

handshake_putB

Store or update one credential. Requires an open session token.

Inputs: name (required), value (required), session (required), note, +1 more.

handshake_statusA

Is the vault open? Shows whether a session is live, how long is left, and how many secrets exist. Needs no token — call this first when a credential is needed.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: session status, listing names, reading a single credential, writing a credential, and viewing the audit log. There is no meaningful overlap or ambiguity between them.

    Naming Consistency4/5

    All tools share the handshake_ prefix and use lowercase snake_case, which is predictable. However, status and log are nouns while list, get, and put are verbs, so the naming pattern is not perfectly uniform.

    Tool Count5/5

    Five tools is a well-scoped set for a credential vault with auditing. Each tool serves an essential function without redundancy or bloat.

    Completeness3/5

    The set covers status checking, listing, reading, writing, and audit logging, which handles the core workflow. However, there is no delete/remove operation for credentials, which is a notable lifecycle gap for a secrets vault.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • agentkeychain

      linsipeng
      A
      license
      Not graded
      quality
      B
      maintenance
      Provides a zero-knowledge credential vault for AI agents, allowing secure storage, retrieval, and management of secrets with cross-agent delegation and tamper-evident audit.
      MIT

    • keymaster-mcp

      kiraa06
      A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to look up stored logins by URL, name, or alias and use them without seeing the secrets, injecting authentication into HTTP requests, running commands with credentials in the environment and scrubbed output, and fetching 2FA codes, subject to per-credential policies and user approval.
      23
      MIT

    • keystash MCP Server

      THUboran
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to list entries and metadata, run commands with secrets injected as environment variables while scrubbing every value from the output, copy secrets straight to the clipboard, and generate or store new secrets without their plaintext ever entering the conversation. Obvious dumpers are refused and destructive edits require explicit confirmation, closing off accidental exposure paths.
      68 PyPI
      MIT

    • llm-vault-mcp

      Koality-Assured
      A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to use vault-stored credentials without ever exposing plaintext secrets to model context, transcripts, or telemetry. It decrypts AES-256-GCM envelopes locally via WebCrypto, resolves opaque secret handles into subprocess environments and outbound HTTP requests, issues auto-zeroizing time-bounded leases, and scrubs echoed credentials from output.
      19
      MIT