botrelay-mcp

Local stdio MCP server for BotRelay. Cursor (or another MCP client) launches this process on your machine. It uses the BotRelay Python SDK (Client(api_key, vault_key, base_url)), calls the BotRelay REST API, and decrypts ciphertext locally.

The private Cursor / Grok Bot plugin that wraps it (setup fields, skill, local install) is plugins/botrelay. This package is not a hosted service and is not published to the public marketplace.

Architecture

Cursor / agent  --stdio JSON-RPC-->  botrelay-mcp (this process)
                                         |  Authorization: Bearer BOTRELAY_API_KEY
                                         v
                                   BotRelay API (ciphertext only)
                                         |
                                         v
                                   decrypt with BOTRELAY_VAULT_KEY
                                   (never leaves this process)

• BOTRELAY_API_KEY and BOTRELAY_VAULT_KEY stay in the local process environment.
• The vault key is never sent to staging, production, or any decryption host.
• No Ansible playbook, Docker Compose, or droplet container change is required. The existing Ansible deploy remains responsible only for the BotRelay API (and web UI). This MCP server does not run on the droplet.

Stdout is the MCP protocol. Diagnostics go to stderr. Tools never log secret values or keys.

Customer install (PyPI / PATH)

After release to PyPI, botrelay-mcp installs its matching botrelay SDK automatically. No BotRelay checkout or MCP config file edit is required. Use Python 3.11 or newer:

python3 -m venv ~/.venvs/botrelay-mcp
source ~/.venvs/botrelay-mcp/bin/activate
python -m pip install --upgrade pip
python -m pip install botrelay-mcp

The activated environment puts botrelay-mcp on PATH. The command starts the local stdio server and is meant to be launched by an MCP client, so it waits for JSON-RPC on standard input:

botrelay-mcp

Press Ctrl-C to stop a manual smoke run. The server does not contact the API until a tool is called.

API URL

Point the client at the BotRelay API and keep keys local:

export BOTRELAY_API_URL=https://api.botrelay.ai
export BOTRELAY_API_KEY=brt_live_...          # agent token from vault create
export BOTRELAY_VAULT_KEY=...                 # standard base64 of the 32-byte vault key

Create those values with the CLI (botrelay vault create); vault_key is printed once and never stored by the API.

Configure an MCP client

Use the installed console script in the client configuration. Keep the environment above active when the client starts, or otherwise make botrelay-mcp available on its PATH.

Cursor mcp.json

User-level: ~/.cursor/mcp.json. Project-level: .cursor/mcp.json (do not commit filled values). The default configuration runs the PyPI console script:

{
  "mcpServers": {
    "botrelay": {
      "command": "botrelay-mcp",
      "args": [],
      "env": {
        "BOTRELAY_API_URL": "https://api.botrelay.ai",
        "BOTRELAY_API_KEY": "YOUR_AGENT_TOKEN",
        "BOTRELAY_VAULT_KEY": "YOUR_BASE64_VAULT_KEY"
      }
    }
  }
}

Never put real tokens in git.

From source / developers

For local package development, from the monorepo root create a checkout virtual environment and install the packages in editable mode. The plugin launcher will discover the checkout through .repo-root and use this .venv; no committed MCP configuration needs to change:

python3 -m venv .venv
source .venv/bin/activate
pip install -e packages/sdk-python -e apps/mcp
bash plugins/botrelay/scripts/install-local.sh

apps/mcp/examples/launch.sh is an optional wrapper around the installed console script. It requires the two keys and defaults BOTRELAY_API_URL to https://api.botrelay.ai.

Tools

There is no safer remote “action” API. The agent contract is metadata listing plus local decrypt-on-get (Client.secrets.get).

get_secret is sensitive: the plaintext goes to the calling agent. Do not paste it into logs or chat. Prefer list_secrets when you only need labels.

Security limitations

• The MCP client (and the model context) sees whatever get_secret returns.
• Keys in mcp.json are as sensitive as the vault. Restrict file mode (0600).
• This server does not add step-up MFA (backlog item 4). Do not store high-sensitivity types on staging until that exists.
• Ciphertext listing is stripped; do not treat metadata as authorization.
• Not published as a public Cursor marketplace plugin. Private packaging: plugins/botrelay.

Tests

pip install -e packages/sdk-python -e apps/mcp
pytest apps/mcp/tests