Getting started with the MCP server

oneguard-mcp is an MCP server that puts the OneGuard CLI in front of an AI agent. Ask your agent to sync a project's secrets, rotate a database password, or check who changed a secret last week — without pasting anything sensitive into a chat.

It shells out to the oneguard binary you already have installed. No new backend, no second login: whatever the CLI can do, this exposes.

Requirements

• Node.js 18 or newer

• The OneGuard CLI 1.3.0 or newer — see installing the CLI. 1.2.0 still works, but the server then falls back to reading the CLI's human-readable output and to storing a credential on disk; oneguard_status says so when that is the case.

• A OneGuard API key

• git, which npx uses to fetch the server

There are no dependencies to install and nothing to build. The MCP protocol is implemented directly, so npx fetches the repository and runs it.

Connect it

Claude Code

claude mcp add oneguard -s user \
  --env ONEGUARD_API_KEY=og_your_key \
  -- npx -y github:oneguard-sa/oneguard_mcp#v0.4.0

Claude Desktop or Cursor

In claude_desktop_config.json or mcp.json:

{
  "mcpServers": {
    "oneguard": {
      "command": "npx",
      "args": ["-y", "github:oneguard-sa/oneguard_mcp#v0.4.0"],
      "env": {
        "ONEGUARD_API_KEY": "og_your_key"
      }
    }
  }
}

Then ask your agent "what's my OneGuard connection status?" — it should report your organization id and whether the key can write.

Prefer a local clone

npx re-resolves the repository each time a server starts, which adds a few seconds to every session. If that bothers you, or you work offline, clone it once instead:

git clone --branch v0.4.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

This is the fastest option to start, and updating is git fetch --tags && git checkout <new tag>.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | ONEGUARD_API_KEY | — | Initializes the session on the first tool call | | 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 tool that changes anything | | ONEGUARD_MCP_TIMEOUT_MS | 60000 | Per-command timeout |

Local and remote

This is a local server: it speaks MCP over stdio and runs on your machine, next to the CLI and the files it writes. That is what lets it put a decrypted .env on your disk without those values crossing the network again.

Using OneGuard from claude.ai on the web, or from ChatGPT, would need a remote HTTP server with OAuth — a different piece of work, and not what this package is.