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.2.0 or newer — see installing the CLI
• A OneGuard API key

There are no npm dependencies to install. The MCP protocol is implemented directly, so npx fetches one small package and runs it.

Connect it

Claude Code

claude mcp add oneguard -s user \
  --env ONEGUARD_API_KEY=og_your_key \
  -- npx -y oneguard-mcp

Claude Desktop or Cursor

In claude_desktop_config.json or mcp.json:

{
  "mcpServers": {
    "oneguard": {
      "command": "npx",
      "args": ["-y", "oneguard-mcp"],
      "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.

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 credential store for the agent's session | | 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.