Docs/Risk Governance/Write Gates & PINs

Write Gates & PINs

To prevent AI models from running updates autonomously without human validation, Bollard enforces physical verification for all write operations. This confirmation is handled by a local HTTP bridge running inside your editor extension.

1. The PIN Generation Flow

When a query is scored as MEDIUM, HIGH, or CRITICAL risk, the execution blocks and enters a secure gating state:

  1. The server detects the local extension port from the BOLLARD_EXTENSION_PORT environment variable.
  2. It sends an HTTP POST request to the extension's local /request_pin endpoint containing the SQL query payload.
  3. The extension displays a native desktop notification containing a unique 4-digit security PIN and copies the code to your system clipboard.
  4. The server pauses execution and returning a markdown warning, prompting the AI agent to request the PIN from the user.
  5. Once you provide the PIN, the AI agent invokes the tool again passing the PIN as an argument, allowing the server to verify the key and execute the SQL safely.

2. The Extension Bridge

The HTTP bridge acts as a validation loop. Because the MCP server runs in a headless background shell, it cannot draw visual UI dialogs. The bridge delegates this responsibility to the local VS Code extension.

  • Clipboard Security: By automatically copying the PIN to your clipboard, Bollard minimizes manual typing. You can quickly paste the PIN into the chat dialog.
  • Session Scopes: PINs are single-use tokens. Once validated by execute_query, the PIN is immediately expired to prevent reuse of authorization keys.
B
Bollard — Write Authorization Required
Query will modify 24 rows. Your security PIN is 7 4 9 1 — copied to clipboard.
Enter PIN in your editor chat to authorize execution.

3. Command-Line Restrictions

If you run the MCP server directly in a terminal shell (outside Cursor or VS Code where the notification extension bridge is not active), write queries are blocked by default:

Write operations are blocked outside the Bollard VS Code Extension.
Please use the Extension Host window to run write queries safely.

To run write scripts in terminal shells, ensure you run in read-only connection mode, or connect under configurations that do not trigger write events.

4. Admin Mode Overrides

Queries scored as EXTREME risk (such as DROP TABLE, TRUNCATE, or database drops) are blocked immediately under default connection sessions.

To bypass this block for legitimate admin maintenance operations:

  • You must disconnect and re-establish the connection specifying mode="admin" inside the connect_database() parameters.
  • Under admin mode, EXTREME risk operations are allowed to proceed through the standard security PIN gate instead of being rejected.