DBMCP

connect_database

Establish a pooled connection to a database to enable subsequent operations, returning a connection ID. Choose a named configuration or direct SQLAlchemy URL.

Instructions

Connect to a database.

Establishes a pooled connection to a database. Required before any other database operations. Returns a connection_id for subsequent calls.

Two connection methods:

connection_name: Use a named connection from dbmcp.toml config file
sqlalchemy_url: Connect directly with a SQLAlchemy URL (e.g., 'postgresql://user:pass@host/db')

Provide exactly one of connection_name or sqlalchemy_url.

MSSQL URL query parameters (mssql+pyodbc://...):

authentication_method: sql | windows | azure_ad | azure_ad_integrated (default: sql when credentials are present, else windows)
trust_server_cert: true | false (default: false)
tenant_id: Azure AD tenant (optional)

Example (MSSQL): mssql+pyodbc://user:pass@host/db?authentication_method=sql&trust_server_cert=true

Args: connection_name: Named connection from config file (optional) sqlalchemy_url: SQLAlchemy connection URL (optional)

Returns: TOON-encoded string with connection details:

    status: "success" | "error"
    connection_id: string              // on success only
    message: string                    // on success only
    dialect: string                    // on success only
    schema_count: int                  // on success only
    has_cached_docs: bool              // on success only
    error_message: string              // on error only

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sqlalchemy_url`	No
`connection_name`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses pooled-connection behavior, the prerequisite requirement, MSSQL-specific defaults, and a detailed TOON-encoded success/error return contract. It does not cover connection lifecycle, cleanup, or authentication requirements beyond URL details, but the transparency is still substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well organized and front-loaded, with the purpose and prerequisite stated first, followed by connection methods, MSSQL details, and the return format. The 'Args' section partially repeats earlier prose, but it usefully maps concepts to actual parameter names, so the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and an uninformative schema, the description covers the connection lifecycle, input methods, mutual exclusivity, error handling, and response fields. The sibling tools are all downstream consumers, and the prerequisite relationship is explicit. No significant missing information prevents an agent from calling this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only two unannotated optional strings with 0% description coverage, so the description must compensate. It defines connection_name versus sqlalchemy_url, gives example URLs, documents MSSQL query parameters with defaults, and enforces the useful 'exactly one' constraint. This fully compensates for the uninformative schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Connect to a database' and 'Establishes a pooled connection' that returns a connection_id. It also positions the tool as 'Required before any other database operations', which differentiates it from the sibling query and inspection tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear when-to-use signal: 'Required before any other database operations.' It also explains the two mutually exclusive connection methods and explicitly says 'Provide exactly one of connection_name or sqlalchemy_url', which is strong usage guidance. It does not name alternative tools or state when not to use the tool, so it stops short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server