# Guardian MCP server

> Routes agent tool calls through a human authority layer to enforce allow, ask, or deny decisions before execution.

- Repository: https://github.com/Odingard/guardian-sdk
- Page: https://hostedmcp.org/servers/odingard/guardian-mcp
- Transport: stdio
- Stars: 1
- License: Apache-2.0
- Latest version: 0.5.0

## Install

### Claude Code

```sh
claude mcp add --env 'GUARDIAN_AGENT_CREDENTIAL=<YOUR_GUARDIAN_AGENT_CREDENTIAL>' --env 'GUARDIAN_BASE_URL=<GUARDIAN_BASE_URL>' --env 'GUARDIAN_CONNECTION_ID=<GUARDIAN_CONNECTION_ID>' guardian-mcp -- npx -y @odingard/guardian-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@odingard/guardian-mcp"
      ],
      "env": {
        "GUARDIAN_AGENT_CREDENTIAL": "<YOUR_GUARDIAN_AGENT_CREDENTIAL>",
        "GUARDIAN_BASE_URL": "<GUARDIAN_BASE_URL>",
        "GUARDIAN_CONNECTION_ID": "<GUARDIAN_CONNECTION_ID>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "guardian-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@odingard/guardian-mcp"
      ],
      "env": {
        "GUARDIAN_AGENT_CREDENTIAL": "<YOUR_GUARDIAN_AGENT_CREDENTIAL>",
        "GUARDIAN_BASE_URL": "<GUARDIAN_BASE_URL>",
        "GUARDIAN_CONNECTION_ID": "<GUARDIAN_CONNECTION_ID>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"guardian-mcp","type":"stdio","command":"npx","args":["-y","@odingard/guardian-mcp"],"env":{"GUARDIAN_AGENT_CREDENTIAL":"<YOUR_GUARDIAN_AGENT_CREDENTIAL>","GUARDIAN_BASE_URL":"<GUARDIAN_BASE_URL>","GUARDIAN_CONNECTION_ID":"<GUARDIAN_CONNECTION_ID>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@odingard/guardian-mcp"
      ],
      "env": {
        "GUARDIAN_AGENT_CREDENTIAL": "<YOUR_GUARDIAN_AGENT_CREDENTIAL>",
        "GUARDIAN_BASE_URL": "<GUARDIAN_BASE_URL>",
        "GUARDIAN_CONNECTION_ID": "<GUARDIAN_CONNECTION_ID>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add guardian-mcp --env 'GUARDIAN_AGENT_CREDENTIAL=<YOUR_GUARDIAN_AGENT_CREDENTIAL>' --env 'GUARDIAN_BASE_URL=<GUARDIAN_BASE_URL>' --env 'GUARDIAN_CONNECTION_ID=<GUARDIAN_CONNECTION_ID>' -- npx -y @odingard/guardian-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.guardian-mcp]
command = "npx"
args = ["-y", "@odingard/guardian-mcp"]

[mcp_servers.guardian-mcp.env]
GUARDIAN_AGENT_CREDENTIAL = "<YOUR_GUARDIAN_AGENT_CREDENTIAL>"
GUARDIAN_BASE_URL = "<GUARDIAN_BASE_URL>"
GUARDIAN_CONNECTION_ID = "<GUARDIAN_CONNECTION_ID>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'GUARDIAN_AGENT_CREDENTIAL=<YOUR_GUARDIAN_AGENT_CREDENTIAL>' -e 'GUARDIAN_BASE_URL=<GUARDIAN_BASE_URL>' -e 'GUARDIAN_CONNECTION_ID=<GUARDIAN_CONNECTION_ID>' guardian-mcp npx -- -y @odingard/guardian-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "guardian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@odingard/guardian-mcp"
      ],
      "env": {
        "GUARDIAN_AGENT_CREDENTIAL": "<YOUR_GUARDIAN_AGENT_CREDENTIAL>",
        "GUARDIAN_BASE_URL": "<GUARDIAN_BASE_URL>",
        "GUARDIAN_CONNECTION_ID": "<GUARDIAN_CONNECTION_ID>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GUARDIAN_AGENT_CREDENTIAL` | yes | yes | Agent credential (gak_…) |
| `GUARDIAN_BASE_URL` | yes | no | Guardian control-plane base URL |
| `GUARDIAN_CONNECTION_ID` | yes | no | Default tool connection id for invocations |
| `COMPOSIO_API_KEY` | no | no |  |
| `GUARDIAN_ADAPTER_ID` | no | no | Optional adapter override |
| `WHATSAPP_TOKEN` | no | no |  |

## Tools (3)

- `guardian_invoke_tool`
- `guardian_claim`
- `guardian_receipt`

## FAQ

### How does Guardian handle tool calls?

Every tool call receives a deterministic decision of ALLOW, ASK, or DENY. ALLOW executes the call, ASK holds it for human approval, and DENY refuses the action.

### Can I use Guardian with my existing MCP servers?

Yes, you can use the proxy mode to put Guardian in front of any stdio or remote MCP server like WhatsApp, Stripe, or Shopify.

### What happens if a file changes after it was approved?

If you use the --pin-file feature and the file content changes before the call is forwarded, the execution is blocked and a content change error is returned.

### Does the upstream server see my Guardian credentials?

No, the upstream server never receives the Guardian settings, ensuring the agent credential remains private.
