Setup & Connections

Getting Bollard connected to your database is simple. It runs as a standard Model Context Protocol (MCP) server over standard input/output streams, meaning any modern editor client (such as Cursor or VS Code) can manage the server daemon process directly.

1. Installation

Bollard is packaged as a standard Python module available on PyPI. You can install it globally, in a project virtual environment, or run it directly from source.

Global Installation (Recommended)

Install the package globally using pip. This automatically registers the bollard-mcp CLI executable in your system path:

pip install bollard-mcp

Virtual Environment Installation

If you prefer to lock dependencies per project or keep your system scope clean, install it in a local Python virtual environment:

# Create virtual environment and activate
python -m venv .venv

# Activate on macOS/Linux
source .venv/bin/activate

# Activate on Windows (PowerShell)
.venv\Scripts\activate

# Install the package
pip install bollard-mcp

Developer Source Installation

To run the latest bleeding-edge updates directly from the source repository:

git clone https://github.com/Bollard-db/Bollard.git
cd Bollard
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -e .

2. Configuring your IDE Client

Because Bollard implements the standard Model Context Protocol (MCP), it integrates out-of-the-box with any modern IDE client that supports MCP servers.

Cursor

To configure Bollard in Cursor:

1. Navigate to Cursor Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Configure the server with the following settings:
   • Name: bollard
   • Type: command
   • Command: bollard-mcp (or the full absolute path to the executable inside your virtualenv)

Alternatively, you can edit your Cursor MCP config file directly:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS/Linux: ~/.cursor/mcp.json

{
  "mcpServers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

{  
  "mcpServers": {  
    "bollard": {  
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }  
  }  
}  

GitHub Copilot (VS Code)

To configure Bollard with GitHub Copilot Chat in VS Code, you can set up the mcp.json file structure either globally or locally for your workspace. Note that Copilot expects the top-level key to be "servers" instead of "mcpServers".

Option A: Global User Setup (All projects)

1. Open the VS Code Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
2. Search for and select MCP: Open User Configuration.
3. If the configuration file is empty, paste the full JSON below. If you already have other servers configured, add the "bollard" block inside your existing "servers" object:

{
  "servers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

Option B: Local Workspace Setup (This project only)

1. Create a folder named .vscode at the root of your project workspace.
2. Create a file named mcp.json inside it (i.e. .vscode/mcp.json).
3. If this is a new configuration file, paste the full JSON below. If you already have other servers configured, add the "bollard" block inside your existing "servers" object:

{
  "servers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

VS Code (with Cline / Roo Code / Claude Dev)

To use Bollard with Claude/Roo agents in VS Code using the Cline extension:

1. Click the Cline tab in the sidebar.
2. Click the gear icon (Settings) in the top-right corner.
3. Scroll down to the MCP Settings section and click Edit MCP Settings.
4. Add the server configuration to the JSON file:

The configuration file is located at:

• Windows: %APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json
• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

Windsurf

To use Bollard inside Windsurf:

Add the configuration under your global Windsurf MCP configuration file located at:

• Windows: %USERPROFILE%\\.codeium\\windsurf\\mcp_config.json
• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

Claude Desktop Client

To configure Bollard with the official Claude Desktop app:

Edit your Claude Desktop configuration file located at:

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bollard": {
      "command": "bollard-mcp",
      "env": {
        "BOLLARD_DEBUG": "false"
      }
    }
  }
}

OpenAI Codex

To configure Bollard with OpenAI Codex, you can add the server under the [mcp_servers] table in your Codex configuration file:

• Windows: %USERPROFILE%\.codex\config.toml
• macOS/Linux: ~/.codex/config.toml

[mcp_servers.bollard]
command = "python" # or "bollard-mcp" if installed globally via pipx
args = ["-m", "bollard_mcp.server"]
cwd = "/path/to/bollard-mcp" # optional: set workspace directory

Cross-Platform OS Binary Path Resolution

If your IDE cannot find the bollard-mcp command globally, replace "command": "bollard-mcp" with the full absolute path where Python installed the binary:

• Windows (Global Pip): "C:\\\\Users\\\\YourUsername\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python310\\\\Scripts\\\\bollard-mcp.exe"
• macOS/Linux (Global Pip): "/usr/local/bin/bollard-mcp" or "/Users/YourUsername/.local/bin/bollard-mcp"
• Virtual Environment: "/path/to/your/project/.venv/bin/bollard-mcp" (macOS/Linux) or "C:\\\\path\\\\to\\\\your\\\\project\\\\.venv\\\\Scripts\\\\bollard-mcp.exe" (Windows)

3. Environment Variables

You can fine-tune Bollard using the following environment variables. Place them in your editor's MCP configuration settings or in a .env file in the server's working directory.

4. PgBouncer & Transaction Poolers

When connecting to transaction-pooled database endpoints (like Supabase's pooler.supabase.com on port 6543), database drivers often crash with a DuplicatePreparedStatementError.

Bollard Solution: The database adapter checks if the connection URL contains "pooler" or "pgbouncer". If matched, it disables statement caching by setting statement_cache_size = 0 on the underlying asyncpg connection engine. This ensures query execution stability over pooled ports.

5. Connection String Examples by Provider

Here is the reference for connection formats required for popular database hosting providers:

Local Docker (PostgreSQL)

If you are running a local database inside a Docker container for development and testing:

• Connection String: postgresql://[user]:[pass]@localhost:5432/[db_name]
  Example: postgresql://postgres:postgres@localhost:5432/dbcopilot
• Seeding the Database: You can seed a local test database populated with tables (users, orders, secrets) to test safety limits and query interception rules:
  python examples/create_postgres_test_db.py

Supabase (PostgreSQL)

• Session (Direct Port 5432): postgresql://postgres.[ref]:[pass]@aws-0-[region].pooler.supabase.com:5432/postgres
• Transaction Pooler (Port 6543): postgresql://postgres.[ref]:[pass]@aws-0-[region].pooler.supabase.com:6543/postgres?pgbouncer=true
  Note: Bollard automatically disables statement caching on this port to prevent session crashes.

Neon (Serverless Postgres)

• Connection String: postgresql://[user]:[pass]@[neon-id].aws.neon.tech/neondb?sslmode=require
  Note: SSL is required by Neon. Bollard will automatically append sslmode=require if you omit it.

Render & Railway (PostgreSQL)

• Connection String: postgresql://[user]:[pass]@[host].oregon-postgres.render.com/[db_name]?sslmode=require

Turso (Edge SQLite)

• Connection String: sqlite+libsql://[db-name]-[org-name].turso.io?uri=... or standard local SQLite path: sqlite:///c:/path/to/local.db

MongoDB Atlas (Document Database)

• Connection String: mongodb+srv://[user]:[pass]@[cluster].mongodb.net/[db_name]?retryWrites=true&w=majority
  Note: Requires installing Bollard with MongoDB support: pip install bollard-mcp[mongodb].