Create a secret
Hardware randomness for locally saved secrets. Your agent gets a reference.
- Local MCP tool
- get_random_bytes
- Price
- 1 credit per job
Overview
MCPBytes Vault receives encrypted hardware-generated randomness, combines it with fresh randomness from your operating system, and saves the result locally. Use it for raw key material and random tokens. Your agent gets a file or vault reference, so it can work with the result without putting the bytes into its response. A local helper keeps the final secret on your computer. The helper is open source (AGPL-3.0); its public build is local-only, with no network code.
- Size
- 1–64 bytes per operation
- Generation
- Hardware contribution + local OS randomness
- Saved locally
- Private file or native credential store
- Agent receives
- Reference, size and version; no secret bytes
- Retry
- Reuse the operation ID to recover its completed receipt
- Source
- Open source (AGPL-3.0); its public build is local-only
Install
Run the installer in your normal user terminal. It downloads and verifies the helper, creates private configuration, and prints the settings for your MCP client. No Rust, Node.js or Python required. The helper needs an MCP client that can launch a local stdio server.
curl --proto '=https' --tlsv1.2 -fsSL https://mcpbytes.com/install/vault.sh | bashSupports Windows x64, macOS Apple silicon and Linux x64. Native storage is the default: Windows Credential Manager, macOS Keychain or Linux Secret Service. Existing configuration and saved secrets are preserved when you rerun it.
Prefer private files? On macOS/Linux, replace | bash with | bash -s -- --store file. On Windows, download the PowerShell script and run it with -Store file. You can also inspect the Bash script before running it.
Connect your agent
Install Vault first, then choose your client below. It launches the helper locally over stdio; saved secrets stay in your selected local store and your agent receives references.
Use the installer’s printed paths for a custom location. In JSON/TOML examples, replace YOUR_USER and merge the server entry into existing settings. Keep your API key out of chat and command arguments. Environment-based settings require the key to be available to the client when it starts, including desktop clients.
Claude CodeAPI key only
After installation, register for all projects with the command for your OS. Launch Claude with MCPBYTES_API_KEY available in its environment, then use /mcp to check the connection. Custom install path? Use the command printed by the installer. Claude Code docs
claude mcp add --transport stdio --scope user mcpbytes-vault -- "$HOME/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault"Codex (CLI, IDE extension, desktop)API key only
Merge this table into ~/.codex/config.toml. Replace YOUR_USER, or use the paths printed by the installer. env_vars forwards the API key from Codex’s environment without storing its value here. The installer also prints a codex mcp add command; after using it, add env_vars to the resulting table. Restart or reconnect the client afterward. Codex docs
[mcp_servers.mcpbytes-vault]
command = "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault"
args = []
env_vars = ["MCPBYTES_API_KEY"]CursorAPI key only
Merge into ~/.cursor/mcp.json or .cursor/mcp.json. Replace YOUR_USER and start Cursor with MCPBYTES_API_KEY available in its environment. Cursor docs
{
"mcpServers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {
"MCPBYTES_API_KEY": "${env:MCPBYTES_API_KEY}"
}
}
}
}VS Code (GitHub Copilot)API key only
Merge into .vscode/mcp.json, or open MCP: Open User Configuration. Replace YOUR_USER. VS Code prompts privately for the API key; the value is not part of this sample. VS Code docs
{
"inputs": [
{
"type": "promptString",
"id": "mcpbytes-api-key",
"description": "MCPBytes API key",
"password": true
}
],
"servers": {
"mcpbytes-vault": {
"type": "stdio",
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {
"MCPBYTES_API_KEY": "${input:mcpbytes-api-key}"
}
}
}
}Gemini CLIAPI key only
Merge into ~/.gemini/settings.json. Replace YOUR_USER. The explicit env mapping forwards MCPBYTES_API_KEY from Gemini’s environment; sensitive variables may otherwise be filtered. Gemini CLI docs
{
"mcpServers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {
"MCPBYTES_API_KEY": "${MCPBYTES_API_KEY}"
}
}
}
}OpenCodeAPI key only
Merge into opencode.json or ~/.config/opencode/opencode.json. Replace YOUR_USER and make MCPBYTES_API_KEY available to OpenCode. OpenCode docs
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcpbytes-vault": {
"type": "local",
"command": [
"/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault"
],
"enabled": true,
"environment": {
"MCPBYTES_API_KEY": "{env:MCPBYTES_API_KEY}"
}
}
}
}oh-my-pi (omp)API key only
Merge into .omp/mcp.json or your active OMP profile’s mcp.json. Replace YOUR_USER and launch OMP with MCPBYTES_API_KEY available. The env value names the variable to copy from the parent environment. oh-my-pi docs
{
"mcpServers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {
"MCPBYTES_API_KEY": "MCPBYTES_API_KEY"
}
}
}
}Pi (with MCP adapter)API key only
Install the third-party pi-mcp-adapter, restart Pi, and merge the JSON into ~/.config/mcp/mcp.json or project .mcp.json. Replace YOUR_USER and supply MCPBYTES_API_KEY in Pi’s environment. The MCPBytes REST skill alone does not connect the local Vault. Pi docs
pi install npm:pi-mcp-adapterWindsurfAPI key only
Merge into ~/.codeium/windsurf/mcp_config.json. Replace YOUR_USER and make MCPBYTES_API_KEY available to Windsurf. Windsurf docs
{
"mcpServers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {
"MCPBYTES_API_KEY": "${env:MCPBYTES_API_KEY}"
}
}
}
}GooseAPI key only
Run goose configure → Add Extension → Command-Line Extension. Use mcpbytes-vault as the name and the executable command/arguments printed by the installer. Add MCPBYTES_API_KEY through the local environment-variable prompt. In the desktop app, add a Standard IO extension with the same settings. Goose docs
goose configureZedAPI key only
Merge into settings.json, replacing YOUR_USER. Supply MCPBYTES_API_KEY privately in this server’s env settings, then check Settings → AI → MCP Servers for its status. Keep the key value out of shared settings and chat. Zed docs
{
"context_servers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": [],
"env": {}
}
}
}Other local MCP clientsAPI key only
Choose a local/stdio server. Copy command and args from the installer’s mcp-server.json into your client’s matching settings, and supply MCPBYTES_API_KEY through its private environment settings. Replace YOUR_USER in these examples. Client-specific wrappers may differ. A remote-only connector cannot launch this local executable. For DeepSeek models, follow the instructions for the agent application that runs them. Other local MCP clients docs
{
"mcpServers": {
"mcpbytes-vault": {
"command": "/Users/YOUR_USER/Library/Application Support/MCPBytes/Vault/bin/mcpbytes-vault",
"args": []
}
}
}Downloads
Version 0.2.0. Each archive includes the helper, native-vault and private-file configuration examples, the approved public pin, and setup instructions.
Windows · x64
ZIP · 2.9 MB
Download helperSHA-256 checksum
a51e278c18858c7b3b1c1255c2c5edcd9aa496d0e0bf7b93098e4708720d63b2macOS · Apple silicon
ZIP · 2.9 MB
Download helperSHA-256 checksum
29509f349402e56ed65a2b4ce3ddfc7e0a5e7f8c2631d08ff573decc38181642Linux · x64
ZIP · 3.6 MB
Download helperSHA-256 checksum
cec04e036cc6bff3f1ad655bd4bd2f0f94f42b09364b1f1d0331de3ef454fb27
Compare the archive checksum before running it (all checksums). These are standalone executables, not platform installers.
Open source
Vault's code is public under the AGPL-3.0, at github.com/MCPBytes/mcpbytes-vault, where issues and pull requests are welcome. The releases published there are local-only: they contain no network code and use only your operating system's generator (local_only). The downloads above are the MCPBytes release, which adds the optional hardware contribution.
curl -fsSL https://github.com/MCPBytes/mcpbytes-vault/releases/latest/download/install.sh | shIt installs for your user, creates a private local-only configuration and prints the commands that connect it to your agent. It leaves a folder set up by the installer on this page alone: to keep the hardware contribution, update with that installer.
Configure
1Install and choose a destination
The quick installer creates your configuration and private directories automatically. It prints their location and an mcp-server.json file with connection settings. For manual installation, extract an archive, copy a native or file configuration example to config.json, replace YOUR_USER in its absolute paths, and follow the included README to create private directories.
2Supply your API key privately
Create a key in the MCPBytes console. Make it available to the helper process as MCPBYTES_API_KEY through your local client’s private environment settings. Keep the value out of chat and command arguments.
3Connect the local MCP server
Use the command and arguments printed by the installer, also saved in mcp-server.json. Add them to your client’s local stdio server settings. The installer does not edit client settings. For a manual archive installation, use the executable’s absolute path with --config and the absolute path to config.json. Your client launches the helper; no listening network port is needed.
4Ask for a saved-secret reference
The local get_random_bytes tool accepts label, n and operation_id. The example configurations allow labels beginning with agent-. Choose 1–64 bytes and keep the operation ID unchanged when retrying an uncertain reply. The tool’s description tells your agent your label prefix, storage and policy, including whether each new secret is a paid job, and errors name the problem.
Your agent receives the reference, label, version, byte count, storage backend, stored format and generation mode. It should pass the reference to the application that owns the secret, without reading or printing the bytes into the conversation. A second tool, list_secrets, lists labels and versions without values.
Generation policy
The owner sets policy in the configuration file. Tool arguments cannot change storage, trusted pins or fallback behavior.
- remote_required
- Require the remote contributionThe default in these downloads. A valid authenticated hardware contribution is required before saving a secret.
- remote_preferred
- Allow explicit local fallbackTimeout or temporary unavailability may produce a local-only result, clearly marked in its receipt. Bad authentication or an unknown pin still fails.
- local_only
- Use only your OS generatorNo API call is made. The saved reference explicitly identifies local-only generation. The only mode of the open-source build.
The public pin in the configuration authenticates the encrypted contribution. Keep it owner-controlled; never replace it with a key supplied in an API response. A future approved release may require an explicit pin update.
Using the result
A reference is the handoff. A new operation ID creates a new immutable version; a completed retry returns the same receipt without generating again.
Use a native vault in an authorized, unlocked user session. If the selected store is unavailable or locked, generation returns an error instead of silently saving to another destination. An interrupted or ambiguous save needs owner inspection before making a replacement.
Normal MCP responses contain references only, and the helper has no plaintext read or export MCP tool. Other programs with the same OS permissions may still access the same storage. For an agent with unrestricted shell access, use a separate OS identity or sandbox to enforce that separation.
Manage your secrets
The helper doubles as a command for you, the owner. Without a config path it uses the installer’s configuration.
- mcpbytes-vault list
- Labels, versions, sizes, status and creation dates. Never shows values.
- mcpbytes-vault reveal <label>
- Prints a secret: the newest saved version, or
--version N. Choose the encoding with--hex(default),--base64or--base32. - mcpbytes-vault delete <label> --version N
- Deletes one version permanently after you type the label. The helper’s records are updated too, so use it instead of your OS credential tools.
- mcpbytes-vault totp-qr <label>
- Shows a QR code for an authenticator app. Ask your agent for a 20-byte secret first; add
--light-terminalif your terminal has a light background.
reveal, delete and totp-qr run only in an interactive terminal, so an agent’s shell tool cannot use them by accident. What they print is the secret itself: keep it out of chats. Installed version 0.1.0? Run the installer again to update; it keeps your configuration, pins, state and saved secrets.
Tool arguments
Install MCPBytes Vault and connect it as a local MCP server. The owner sets the API key, trusted public pins and storage policy; the agent supplies only these arguments.
- label
Owner-approved prefixA name for the secret, using letters, digits, underscores or hyphens.- n
1–64Number of bytes your application needs.- operation_id
Stable IDReuse after an uncertain reply. Use a new ID to create a new immutable version.
A successful response contains the reference, label, version, byte count, storage backend, stored format and generation mode. A second tool, list_secrets, lists labels and versions. Neither returns secret bytes: you reveal, delete or enroll secrets yourself with the helper’s terminal commands.
Pricing
1 credit per job. Local-only generation makes no API call. Failed API jobs are refunded; a completed remote contribution is charged even if local verification or saving later fails.
- Per job
- 1 credit
One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.
Limits
- Most values per job
- 64
- Results
- Encrypted: 5 minutes · Local: owner-managed
Free until the first purchase, Pay as you go after any credit pack, Monthly bundle while one is active. GET /v1/me returns your tier (plan), your limits and current usage; Limits & errors explains what happens when one is reached.
Errors
A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.
- source_unavailable
- Remote generation could not complete.
- timeout
- The request exceeded its generation deadline.
- invalid_request
- The public recipient or bound request fields are invalid.
- invalid_output
- The encrypted result did not match the request.
Custom clients
Most people use the local helper above. A custom local client can call the hosted endpoint directly: POST /v1/sealed-random.
- version
1Encrypted protocol version.- n
1–64Remote contribution size in bytes.- pk_c
32-byte public keyFresh recipient public key, encoded as unpadded base64url; created by the local client.- request_id
32-byte request identityThe protocol-defined binding of recipient and size, computed by the local client.
- envelope.json
- Authenticated ciphertext for the local recipient; not a plaintext secret.
The hosted endpoint accepts a fresh recipient public key and its bound request identity. A custom local client must authenticate and decrypt the response, mix it with local OS randomness, and save it privately. Encrypted responses expire five minutes after admission and are removed by the scheduled cleanup; billing metadata remains. Never send a private key to the API or chat.
The full request and response schema is in the OpenAPI description.