Skip to main content
Glama
oneguard-mcp

oneguard-mcp

Official
by oneguard-sa

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 .env by 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 oneguard CLI 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_status tells 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.0

Claude 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.js

Update with git fetch --tags && git checkout <new tag>.

Configuration

Variable

Default

Purpose

ONEGUARD_API_KEY

—

Initializes the session on the first tool call. Without it, the agent must call oneguard_init with a key you supply.

ONEGUARD_CLI_PATH

oneguard

Absolute path to the binary, when it is not on PATH.

ONEGUARD_MCP_HOME

~/.oneguard-mcp

Isolated config directory for the agent's session. With CLI 1.3.0+ nothing is written there.

ONEGUARD_MCP_READONLY

false

1 hides every mutating tool.

ONEGUARD_API_URL

production

Override the API endpoint, e.g. https://api.staging.oneguard.one/rpc/. The CLI inherits it.

ONEGUARD_MCP_TIMEOUT_MS

60000

Per-command timeout.

Tools

Tool

What it does

oneguard_env_sync

The main one. Pulls the linked secret into the directory's .env, linking it the first time.

oneguard_env_push

Uploads the local .env back into the linked secret, replacing it.

oneguard_env_status

Is this directory linked, to what, and which variable names are in its .env.

oneguard_env_unlink

Removes the .oneguard link file; leaves .env alone.

oneguard_generate

Generates a random value locally and returns it. Stores nothing.

oneguard_secrets_generate

Generates a value into a secret, merging, without revealing it.

oneguard_vault_list / _add / _rename

Vaults.

oneguard_secrets_list / _add / _edit / _archive / _delete

Secrets.

oneguard_teams_list / _invite / _set_role / _remove

Members, invitations and roles.

oneguard_keys_list / _create / _update / _revoke

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.

oneguard_logs_list

Organization audit log.

oneguard_status / oneguard_init

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.js

No 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.js

A 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 --tags

The 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 tools
oneguard_env_pushPush a local .env back to OneGuardA
Destructive

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 stateB
Read-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_generateGenerate a random valueA
Read-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 sessionA
Idempotent

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 keysA
Read-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 keyA
Destructive

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 keyA
Idempotent

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 logA
Read-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 secretA
DestructiveIdempotent

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 secretA
Destructive

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 contentsA
Destructive

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 vaultA
Read-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 connectionA
Read-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 membersA
Read-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 memberA
Destructive

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 roleA
Idempotent

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 vaultsA
Read-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 vaultA
Idempotent

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

    A3.9/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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