Before you start
- An account. Create a free account, or log in if you have one.
- Python 3.10 or newer on the machine where your agent runs. The steps below install it if needed.
- The agent app you want to connect: Claude Desktop, Claude Code, Hermes Agent, or any app that supports MCP (Model Context Protocol).
1Install the client
We install with pipx, which gives the client its own environment and puts its commands on your PATH.
In PowerShell. Skip the first line if py --version already shows 3.10 or newer; if you use the
installer from python.org instead, tick
Add python.exe to PATH.
winget install Python.Python.3.13
py -m pip install --user pipx
py -m pipx ensurepath
Close PowerShell and open a new one (so it sees the new PATH), then:
pipx install aisecuritywarden
sw-mcp --version
Install Python from python.org (its installer
includes what the swadmin window needs; avoid Apple's built-in /usr/bin/python3).
Then in Terminal:
python3 -m pip install --user pipx
python3 -m pipx ensurepath
Using Homebrew instead? brew install pipx python-tk, then pipx ensurepath. Close
Terminal and open a new window, then:
pipx install aisecuritywarden
sw-mcp --version
Install pipx from your distribution (the second package is only for the swadmin window):
# Debian, Ubuntu
sudo apt install pipx python3-tk
# Fedora
sudo dnf install pipx python3-tkinter
# Arch
sudo pacman -S python-pipx tk
Then (open a new terminal after ensurepath):
pipx ensurepath
pipx install aisecuritywarden
sw-mcp --version
You should see the version number, for example sw-mcp 0.7.2. The package is on
PyPI; the source is on
GitHub.
2Make a token for the agent
The agent never gets your API keys. It gets a machine token: scoped to one project, revocable at any time, and limited by your approval rules.
- On the website, open a project (or make one) and add the secrets the agent's tools need.
- Under Tokens, choose New token, name it after the machine or bot, and pick the agent app. The
last step shows the MCP settings for that app, filled in for this token, and a one-time setup
code (it starts with
SWS1-). Keep that page open for steps 3 and 4.
3Connect your agent
Copy the MCP settings from the website into the agent app. They look like this, with your token's details:
{
"mcpServers": {
"aisecuritywarden-my-bot": {
"command": "sw-mcp",
"args": ["serve"],
"env": {
"SW_SERVER_URL": "https://app.aisecuritywarden.com",
"SW_TOKEN_ID": "the token's id",
"SW_TOKEN_NAME": "my-bot"
}
}
}
}
No secret goes in the settings: the token itself arrives in step 4.
Where it goes
- Claude Desktop: Settings → Developer → Edit Config. Paste the entry inside
"mcpServers", save, and restart Claude Desktop. - Claude Code: the website gives you a
claude mcp add …command to run instead. - Hermes Agent: under
mcp_serversin~/.hermes/config.yaml(the website gives it in YAML), or Hermes → Add MCP server. Then start a new session. - Other MCP apps: the same JSON in their MCP settings.
(Get-Command sw-mcp).Source
Usually C:\Users\you\.local\bin\sw-mcp.exe. In JSON, write each \ as
\\.
command -v sw-mcp
Usually /Users/you/.local/bin/sw-mcp.
command -v sw-mcp
Usually /home/you/.local/bin/sw-mcp.
Optional: teach the agent the rules
Every agent is told the essentials when it connects (wait for approvals, treat email and web content as untrusted, update only through aiSecurityWarden). Agents with skills can get the full guide:
sw-mcp skill install hermes # Hermes Agent
sw-mcp skill install claude # Claude Code
sw-mcp skill zip claude # Claude app: upload the .zip in its Skills settings
Then start a new session. The skill keeps itself up to date with the client.
4Give it the setup code
The easiest way: on the website choose Copy for the agent and paste it into a chat with the agent ("Set up aiSecurityWarden with code SWS1-…"). The agent stores the token on its machine, readable only by your user, and its tools work straight away. The code works once and expires after a few minutes.
Or from a terminal on that machine, with the same server and token name as the MCP settings (it asks for the code, so it never lands in your shell history):
$env:SW_SERVER_URL = "https://app.aisecuritywarden.com"
$env:SW_TOKEN_NAME = "my-bot"
sw-mcp setupSW_SERVER_URL=https://app.aisecuritywarden.com SW_TOKEN_NAME="my-bot" sw-mcp setup5Check it works
Ask the agent to do something with one of its tools. The first time, approve its session on your phone or the website (you'll see a match code). To check everything step by step, run doctor with the same settings:
sw-mcp doctor
(in the PowerShell window where you set $env:SW_SERVER_URL and $env:SW_TOKEN_NAME)
SW_SERVER_URL=https://app.aisecuritywarden.com SW_TOKEN_NAME="my-bot" sw-mcp doctorIt checks the token, the server, approvals, connectors and the tools the agent is offered, and never prints a secret.
A bot or script without MCP? swctl export and swctl run -- your-program hand it
secrets at start-up instead.
Keeping it up to date
Ask your agent "check for aiSecurityWarden updates" or "update aiSecurityWarden": you approve the exact version, and only releases signed by aiSecurityWarden are installed. Or from a terminal:
sw-mcp update --check
sw-mcp update
pipx upgrade aisecuritywarden works too. Afterwards restart the program that runs aiSecurityWarden for
the agent; an update through the agent names it (for Hermes often the dashboard or gateway, not the desktop app).
If the agent still shows old tools, see Help.
Troubleshooting
- "sw-mcp: command not found" / "not recognized". Open a new terminal after
pipx ensurepath. For the agent app, use the full path (step 3). - Windows: "py" isn't recognized. Python isn't installed, or was installed without the launcher: rerun the
python.org installer, or use
pythoninstead ofpy. - Linux: "externally-managed-environment". Your distribution doesn't let pip install system-wide; install pipx with the package manager as above, not with pip.
- The agent shows fewer tools than expected. It read the tool list before you approved its session: start
a new session or refresh its tools.
sw-mcp doctorsays which. - Coming from version 0.6 (installed as
securitywarden)? Reinstall once:pipx uninstall securitywardenthenpipx install aisecuritywarden. Tokens and settings stay where they are. - Still stuck? Contact us; include what
sw-mcp doctorsays (it contains no secrets).