oneguard-mcp
OfficialOneGuard MCP server lets an agent manage OneGuard vaults, secrets, .env sync, credential generation, teams, and audit logs through the installed CLI, while keeping secret values out of tool results.
Initialize or check an isolated OneGuard session and whether the API key can write.
Sync a project directory's
.envfrom a linked secret, check sync status, push.envback to OneGuard, or unlink the directory.List, create, and rename vaults.
List, create, edit, archive, and delete secrets; deletion requires exact name confirmation.
Generate random values locally, or generate a value directly into a secret without revealing it.
List, invite, change roles for, and remove team members; removal requires exact email confirmation.
Read the organization audit log to see who did what and when.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oneguard-mcp sync this folder's secrets from OneGuard"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oneguard-mcp
An MCP server that puts the OneGuard CLI in front of an AI agent — Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP over stdio.
Ask your agent to sync a project's secrets into .env, rotate a database password without ever seeing it, or check who changed a secret last week.
You: sync this folder's secrets from OneGuard
Claude: Which vault? → api-production · marketing-site
You: api-production
Claude: Wrote 12 variables to .env — DATABASE_URL, API_TOKEN, STRIPE_KEY, …It shells out to the oneguard binary you already have installed. No new backend, no second login, no API surface of its own: whatever the CLI can do, this exposes, and whatever it cannot, this does not pretend to.
Zero dependencies. The MCP stdio protocol is implemented directly. Nothing to install, nothing to build, no dependency tree to audit — the whole server is the files in
src/.Secret values do not come back. Tools report variable names and counts. Values are written to and read from your
.envby the CLI itself and never enter the model's context.No credential on disk. With CLI 1.3.0+ the key is handed to each subprocess in its environment and never written anywhere. The agent's session never touches your own
oneguard auth login.
Requirements
Node.js 18 or newer
The
oneguardCLI 1.3.0 or newer — installation. 1.2.0 still works; the server then parses the CLI's human-readable output and stores a credential on disk instead.oneguard_statustells you which mode you are in.A OneGuard API key (dashboard → Vault → API Keys → Add)
Related MCP server: keywarden
Install
Claude Code
claude mcp add oneguard -s user \
--env ONEGUARD_API_KEY=og_your_key \
-- npx -y github:oneguard-sa/oneguard_mcp#v0.5.0Claude Desktop (claude_desktop_config.json) or Cursor (mcp.json)
{
"mcpServers": {
"oneguard": {
"command": "npx",
"args": ["-y", "github:oneguard-sa/oneguard_mcp#v0.5.0"],
"env": {
"ONEGUARD_API_KEY": "og_your_key"
}
}
}
}Then ask the agent "what's my OneGuard connection status?" to confirm it is wired up.
Pin the tag. #v0.5.0 is not decoration: without it you run whatever is on
main at that moment, so a push here would execute on your machine without you
choosing to update. Bump the tag deliberately, after reading the
release notes.
Or clone it once. npx re-resolves this repository every time an MCP server
starts, which adds a few seconds to each session. A local clone is the fastest
option and works offline:
git clone --branch v0.5.0 https://github.com/oneguard-sa/oneguard_mcp.git ~/tools/oneguard-mcp
claude mcp add oneguard -s user \
--env ONEGUARD_API_KEY=og_your_key \
-- node ~/tools/oneguard-mcp/src/index.jsUpdate with git fetch --tags && git checkout <new tag>.
Configuration
Variable | Default | Purpose |
| — | Initializes the session on the first tool call. Without it, the agent must call |
|
| Absolute path to the binary, when it is not on |
|
| Isolated config directory for the agent's session. With CLI 1.3.0+ nothing is written there. |
|
|
|
| production | Override the API endpoint, e.g. |
|
| Per-command timeout. |
Tools
Tool | What it does |
| The main one. Pulls the linked secret into the directory's |
| Uploads the local |
| Is this directory linked, to what, and which variable names are in its |
| Removes the |
| Generates a random value locally and returns it. Stores nothing. |
| Generates a value into a secret, merging, without revealing it. |
| Vaults. |
| Secrets. |
| Members, invitations and roles. |
| API keys: list, create with scoped permissions, change vault access, and revoke. Requires CLI 1.6.0+ and a key with Can create API keys. |
| Organization audit log. |
| Connection and session. |
How it handles secrets
This server sits between a secrets manager and a language model, so the interesting part is what it refuses to do.
Values are not returned. oneguard_env_sync and oneguard_env_push report variable names and a count. The CLI decrypts to disk; nothing in the tool result carries a value. There is a test that asserts this.
Generating a credential never reveals it. oneguard_secrets_generate has the CLI generate the value and store it directly, merging into the secret so every other variable survives. The agent learns that DB_PASSWORD now exists, and nothing more. oneguard_generate is the one tool that returns a value — a value stored nowhere is useless unless returned — and its description steers the model to the other tool whenever the value is destined for a secret.
Your login is not the agent's login. From CLI 1.3.0 the agent's key lives only in the subprocess environment, so there is no stored credential at all. On an older CLI the key is stored, and this server hands each subprocess its own HOME, so an agent session cannot overwrite the key you use in your terminal — and a rejected key here cannot sign you out there.
Destructive tools ask for proof. Deleting a secret requires its exact name; removing a member requires their exact email; revoking a key requires its exact name. Both are checked against the server before anything happens, so an agent working from a half-remembered name is stopped rather than guessing.
Two independent brakes. An API key created as read is refused every write by the server, whatever the client does. ONEGUARD_MCP_READONLY=1 additionally hides the mutating tools so the model never sees them. Use the key for the guarantee, the flag to keep the tool list focused; oneguard_status reports can_write so the agent knows which it has before it tries.
Interactive commands are never invoked. oneguard env sync on an unlinked directory prompts on stdin, which cannot work when no human is on the other end of the pipe. Instead this server returns the list of vaults for you to choose from, writes the .oneguard link itself, then calls the non-interactive env pull. Subprocess stdin is closed, so anything that tries to prompt fails fast instead of hanging.
The link file is byte-compatible with the CLI's own, so a directory linked by the agent keeps working with oneguard env sync in your terminal, and the other way round.
Development
git clone https://github.com/oneguard-sa/oneguard_mcp.git
cd oneguard_mcp
node test/smoke.test.jsNo install step — there are no dependencies. The suite drives the real server over stdio against a mock CLI that reproduces the real binary's output formatting and exit codes: the protocol handshake, the full sync flow, generation, team management, the read-only key path, and the guardrails. 39 checks, no network and no OneGuard account needed.
Against a real account, read-only:
ONEGUARD_API_KEY=og_your_key node test/live-check.jsA note on parsing
The OneGuard CLI prints for humans — there is no --json mode yet — so src/parsers.js turns lines like ID: 84e1d2b3 | Name: production | Archived: false back into objects. Every parser is tolerant of unrecognized lines and every tool also returns the raw stdout, so a formatting change in the CLI degrades rather than breaks.
That file is the seam between the two projects. If the CLI's output changes, live-check.js is the fastest way to notice, and src/parsers.js should be the only file that needs updating.
Releasing
This server is installed straight from this repository, so a release is a tag and a set of release notes — there is no registry in the loop.
npm version minor --no-git-tag-version # bump package.json only
git commit -am "0.4.0"
git tag v0.5.0
git push && git push --tagsThe tag triggers .github/workflows/publish.yml, which runs the test suite,
checks the tag matches package.json, and publishes a GitHub Release. Anyone
pinned to an older tag keeps running it until they change the pin.
Publishing to npm later would not change how any of this works — the package is already shaped for it — but nothing here depends on it.
License
MIT — see LICENSE.
Available Tools
25 toolsoneguard_env_pushPush a local .env back to OneGuardADestructive
Uploads the variables in a directory's .env file into the secret that directory is linked to, REPLACING what the secret held. The reverse of oneguard_env_sync. Confirm with the user first, and tell them which variable names are about to be uploaded. To add a single generated value without touching the rest, use oneguard_secrets_generate instead.
Inputs: project_dir (required), path.
oneguard_env_statusShow a directory's sync stateBRead-only
Reports whether a directory is linked to a OneGuard secret, which one, and which variable names its .env currently holds. Read-only.
Inputs: project_dir (required), path.
oneguard_env_syncSync secrets into a directory's .env fileA
THE MAIN TOOL. Fetches the secret linked to a directory and writes it into that directory's .env file, then remembers the link for next time. Call it with only project_dir when the directory is already linked (it re-pulls the latest values). If it is not linked yet, this returns the list of vaults (or secrets) to choose from — show those to the user, let THEM pick, then call again with vault and secret. Returns only the variable NAMES that were written; values go to disk and are never shown.
Inputs: project_dir (required), path, vault, relink, +1 more.
oneguard_env_unlinkUnlink a directoryAIdempotent
Removes the .oneguard link file from a directory. The .env file on disk is left untouched. Equivalent to oneguard env sync --reset.
Inputs: project_dir (required).
oneguard_generateGenerate a random valueARead-only
Generates one or more random values locally and returns them. Nothing is stored anywhere. Note that the returned value passes through this conversation — if the value is going into a OneGuard secret, use oneguard_secrets_generate instead, which stores it without ever revealing it.
Inputs: count, length, numbers, special, +4 more.
oneguard_initInitialize the OneGuard sessionAIdempotent
Initializes this server's isolated OneGuard session with an API key and verifies it against the backend. Normally you do NOT need to call this: if ONEGUARD_API_KEY is configured on the server, the session initializes itself on the first tool call. Call this only when another tool reports that the server is not initialized, and only with a key the user gave you in this conversation — never invent one. The key is kept for this session only and does not affect the user's own oneguard login in their terminal.
Inputs: api_key.
oneguard_keys_createCreate an API keyA
Creates a new API key and returns the raw secret exactly once. The new key can never be broader than the current key: no extra permission, vault scope, capabilities or lifetime. Use oneguard_keys_list first if you need the current key scope. Only call this when the user explicitly asked to create a key.
Inputs: name (required), never, vaults, permission, +3 more.
oneguard_keys_listList API keysARead-only
Lists the organization API keys with their permission, status, expiry, capabilities and vault scope. Requires the current key to have the "Can create API keys" permission; otherwise OneGuard refuses with a 403.
Inputs: no named parameters.
oneguard_keys_revokeRevoke an API keyADestructive
Disables an API key immediately, cutting off every client using it. This is not reversible from the CLI. Only call this after the user explicitly asked for this specific key, and confirm the exact key name first.
Inputs: key (required), confirm (required).
oneguard_keys_updateUpdate an API keyAIdempotent
Changes an existing key permission, key-management capability, vault-creation capability or vault scope. Omitted fields keep their current value. The current key must have key-management permission, and it can never grant a scope wider than its own. The key can be named by id / 8-character prefix, or exact name.
Inputs: key (required), vaults, permission, can_create_keys, +1 more.
oneguard_logs_listRead the audit logARead-only
Returns the organization audit log — who did what to which resource, and when. Useful for answering "who changed this secret" questions.
Inputs: limit.
oneguard_secrets_addCreate a secretA
Creates a new secret in a vault from a local .env file (preferred) or from a single key/value pair. Prefer from_env_file: passing a value directly means the secret value travels through this conversation. To create a secret holding a NEW generated value, create it here and then use oneguard_secrets_generate, which never reveals the value. Never invent secret values — only use what the user explicitly provided or what is already in their .env file.
Inputs: name (required), vault (required), key, value, +2 more.
oneguard_secrets_archiveArchive a secretADestructiveIdempotent
Archives a secret. It stops appearing as active but is not deleted. Confirm with the user before calling.
Inputs: vault (required), secret (required).
oneguard_secrets_deleteDelete a secretADestructive
Permanently deletes a secret and everything stored in it. This cannot be undone. Only call this after the user has explicitly asked for this specific secret to be deleted, and read the secret name back to them first.
Inputs: vault (required), secret (required), confirm (required).
oneguard_secrets_editReplace a secret's contentsADestructive
Replaces a secret's stored payload. IMPORTANT: this overwrites the whole payload — a single key/value pair replaces every key the secret held. To change one variable while keeping the rest: for a generated value use oneguard_secrets_generate (which merges), otherwise sync the secret to a .env file, edit that file, and push it back with from_env_file. Confirm with the user before calling this.
Inputs: vault (required), secret (required), key, name, +3 more.
oneguard_secrets_generateGenerate a value into a secretA
Generates a random value and stores it in a secret under the given key, WITHOUT returning the value. This merges: every other variable in the secret is preserved (unlike oneguard_secrets_edit, which replaces the whole payload). Use this whenever the user wants a new password, token or key created for a service — it is the safe path, because the value never enters this conversation. Fails if the key already exists unless force is true.
Inputs: key (required), vault (required), secret (required), force, +7 more.
oneguard_secrets_listList secrets in a vaultARead-only
Lists the secrets of a vault: id prefix, name, and whether it is archived. Values are never returned by any tool in this server.
Inputs: vault (required).
oneguard_statusCheck OneGuard connectionARead-only
Verifies that the OneGuard CLI is installed, the session is initialized, and the backend is reachable. Returns the organization id and whether the configured API key may write. Use this first when something is not working, or before a batch of changes.
Inputs: no named parameters.
oneguard_teams_inviteInvite a team memberA
Sends an invitation to join the organization. This emails a real person and grants them access once accepted, so only call it when the user explicitly asked, with the exact address they gave.
Inputs: email (required), role.
oneguard_teams_listList team membersARead-only
Lists the members of the organization with their roles and the 8-character id prefix other team tools accept.
Inputs: no named parameters.
oneguard_teams_removeRemove a team memberADestructive
Removes a member from the organization and revokes their access to every secret in it. This cannot be undone — they would have to be invited again. Only call this after the user explicitly asked for this specific person to be removed, and read their email back to the user first.
Inputs: member (required), confirm (required).
oneguard_teams_set_roleChange a member's roleAIdempotent
Changes an existing member's role in the organization. Promoting to owner or admin grants broad access to every secret, so confirm the person and the role with the user first. The member can be named by email or by their 8-character id prefix. Note that an admin caller cannot modify owners, other admins, or promote anyone to admin or owner — the server enforces this.
Inputs: role (required), member (required).
oneguard_vault_addCreate a vaultA
Creates a new vault in the organization and returns its id. A vault is the container that secrets live in.
Inputs: name (required).
oneguard_vault_listList vaultsARead-only
Lists every vault in the organization, with the 8-character id prefix that other tools accept as a vault argument. A vault is the container that secrets live in.
Inputs: no named parameters.
oneguard_vault_renameRename a vaultAIdempotent
Renames an existing vault. Secrets, links and ids are unaffected — only the display name changes.
Inputs: name (required), vault (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Tools are cleanly grouped by resource (vault, secrets, keys, env, teams, logs, session) and descriptions actively cross-reference the risky pairs, e.g. oneguard_generate vs oneguard_secrets_generate and oneguard_secrets_edit vs oneguard_secrets_generate vs oneguard_env_push. Still, there are four different write paths into a secret payload (add, edit, generate, env_push) and init vs status both concern session state, so a few selections remain judgment calls.
The dominant pattern is oneguard_<resource>_<action> (vault_list, secrets_add, keys_revoke, teams_set_role, env_sync), which is predictable and readable. Deviations are minor: singular 'vault' vs plural 'secrets/keys/teams/logs', 'vault_add'/'secrets_add' vs 'keys_create', and three bare tools (oneguard_init, oneguard_status, oneguard_generate) that drop the resource segment.
25 tools is on the heavy side, but the domain genuinely spans six sub-areas (vaults, secrets, env linking, API keys, team members, audit logs) plus session bootstrap, and each tool maps to a distinct operation with its own safety semantics. Only oneguard_vault_rename and oneguard_init feel marginal, and both serve real lifecycle needs.
Secrets (list/add/edit/delete/archive/generate), API keys (list/create/update/revoke), env linking (sync/status/push/unlink), and team management (list/invite/set_role/remove) all have full lifecycle coverage. Gaps are minor: no vault delete, no way to unarchive a secret, and audit logs are read-only with a single list tool.
Maintenance
Related MCP Connectors
Secrets for developers and agents—secure context and workflows without exposing secret values.
Governed access to sensitive data, secrets and APIs for AI agents. A signed proof for each decision.
Password vault for AI agents with scoped, user-approved access
Encrypted secret store and rotation for autonomous agent credentials
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with direct access to secrets management (get, set, list, delete secrets, and list environments) through the Model Context Protocol, enabling secure secret operations during development.23 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to make authenticated API calls and run commands with secrets injected, while keeping credentials completely hidden from the model, with policy enforcement, grants, and audit logging.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to securely inject API keys and secrets into environment files, configs, or commands without the agent ever seeing the secret values.10 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to scan and audit environment files for leaked secrets, sanitize them, encrypt/decrypt vaults, and run processes with zero-disk secret injection.MIT