API Reference
This section provides a comprehensive technical reference for all tools and resources exposed by the Bollard MCP Server. Integrate these calls into your agentic workflow to manage database connections, introspect schemas, perform safe queries, and log user-corrected behaviors.
Connection Tools
These tools initialize, retrieve, and destroy active database sessions in the server. All other tools require an active connection alias.
connect_database
Connect to a database engine and cache its schema blueprint.
connect_database(
connection_string: string,
alias: string,
mode: "read_only" | "read_write" | "admin" = "read_only",
max_rows: number = 1000,
forbidden_tables: string[] | null = null,
save_credential: boolean = true,
output_mode: "smart" | "raw" | "analytics" = "smart"
)The full connection URL containing credentials, hosts, ports, and databases.
Example: postgresql://postgres:pwd@127.0.0.1:5432/db
A short identifier for referencing the connection (e.g., prod, staging, local_pg).
Access level. Under read_only (default), write operations are strictly blocked. Under read_write, writes are gated. Under admin, drop/truncate checks are elevated.
Default: "read_only"
Hard limit applied to query select results before truncation.
Default: 1000
List of table wildcards to prevent introspecting or selecting (e.g., *.passwords, secrets.*).
Default: null
If true, encrypts and stores connection string variables in the local OS Keyring or backup vault.
Default: true
Controls compression returned to the LLM. Options: smart (truncates large sets), raw (always dumps full text), analytics (sends metrics, zero rows).
Default: "smart"
disconnect
Terminate an active database connection and clear related schema caches.
disconnect(alias: string)The active database identifier to disconnect.
list_connections
Retrieve a list of all currently active database sessions on the Bollard server.
list_connections()Returns a markdown table indicating active aliases, SQL dialects, modes, and connection status.
reconnect_saved
Restore a saved credential connection from the local OS Keyring vault.
reconnect_saved(alias: string)The saved connection alias to reload from OS Keyring storage.
Schema Exploration Tools
Use these tools to inspect database layouts, columns, types, counts, and structures. Caches are used where possible to accelerate queries.
list_tables
List all tables in the connected database alongside estimated row counts and column sizes.
list_tables(connection: string)The connected database alias (e.g., prod).
describe_table
Show columns, datatypes, nullability, keys, default constraints, and foreign key relations for a table.
describe_table(connection: string, table_name: string)The active database alias.
Name of the table to describe (case-sensitive).
get_sample_data
Fetch sample rows to observe formatting, dates, timestamps, and column types.
get_sample_data(connection: string, table_name: string, limit: number = 5)The active database alias.
Target table name.
Max rows to fetch (capped at 25).
Default: 5
refresh_schema
Clear internal schema blueprints and force metadata introspection on the database.
refresh_schema(connection: string)Database alias to sync.
Query Execution Tools
These tools process SQL statements, run intent validations, score risk thresholds, and manage write permissions.
preview_query
Dry-run statements to see intent warnings, safety check rejections, and estimated EXPLAIN cost estimates.
preview_query(connection: string, sql: string)Active database alias.
The SQL statement to check.
execute_query
Run SQL query pipelines under risk gating rules.
execute_query(
connection: string,
sql: string,
confirmed: boolean = false,
pin: string | null = null,
confirmation_phrase: string | null = null,
output_mode: string | null = null
)Active database alias.
SQL query to execute.
Required assertion for write operations.
Default: false
4-digit clipboard confirmation code requested from the extension bridge.
Default: null
String verification sequence required for HIGH or CRITICAL level operations (e.g., "confirm migration").
Default: null
Override connection's default formatting mode for this query results payload (smart, raw, analytics).
Default: null
Table Profiler Tools
Generate column stats natively on the database server.
profile_table
Run native aggregates (null percentages, distinct values, min/max/average, Top-5 categorization distributions) directly in SQL.
profile_table(connection: string, table_name: string)Active database alias.
Name of the table to profile.
Feedback & Corrections
Manage local feedback loops and session logs so AI models adapt their queries based on business rules.
log_correction
Log a semantic correction payload into the persistent storage directory.
log_correction(
connection: string,
original_query: string,
corrected_query: string,
note: string
)Active database alias.
The incorrect query generated by the AI agent.
The correct SQL query syntax or expression.
Plain English instruction explanation (e.g., "signup_date is deprecated, always use created_at").
get_query_history
Inspect query execution records logged during the active session.
get_query_history(connection: string, last_n: number = 10)Active database alias.
Number of query logs to display (capped at 50).
Default: 10
get_corrections
Retrieve all logged corrections and semantic notes recorded for a database.
get_corrections(connection: string)Active database alias.
MCP Resource Endpoints
These standard protocol URIs are automatically loaded and parsed by editor agents (e.g., Cursor, Claude Desktop) to initialize database context when compiling commands.
| URI Pattern | Resource Target Description | Format Returned |
|---|---|---|
bollard://connections | Lists all currently connected database aliases. | Markdown bulleted summaries. |
bollard://schema/{alias} | Introspects and loads the cached SQL blueprint mapping. | Structured database schema blocks. |
bollard://history/{alias} | Loads recent query session logs (up to 10 queries) for continuity context. | Chronological query execution markdown. |
bollard://corrections/{alias} | Retrieves all semantic rules and column corrections logged by the team. | Instruction manual mapping. |
bollard://policies/{alias} | Shows active write permission settings and forbidden table scopes. | Text description policies. |