Legion Database MCP Server: Unified Data Access Layer

This package provides a robust server component, engineered by Legion AI, designed to bridge modern AI assistants with various backend data stores. It utilizes the specialized Legion Query Runner library and integrates deeply with the Model Context Protocol (MCP) Python SDK to expose database capabilities as discoverable resources and actionable tools.

For the full-featured analytical platform, please consult the main Legion AI site. We actively seek feedback on expanding supported database systems.

Core Advantages of Database MCP

Database MCP fundamentally simplifies and secures data interaction for AI workflows:

• Homogeneous Access Layer: Abstracts away database specifics (PostgreSQL, MySQL, MSSQL, etc.), presenting a singular, standardized API endpoint for all connections.
• AI Native Integration: Designed from inception for MCP compatibility, enabling LLMs to query, inspect schemas, and optimize data retrieval using natural language.
• Automatic Schema Induction: Performs zero-touch discovery of underlying database structures, making tables and columns immediately available as context.
• Technology Agnosticism: Standardized toolsets for schema exploration, table enumeration, and query submission function identically irrespective of the underlying RDBMS.
• Credential Separation: Implements secure handling of authentication details, ensuring sensitive connection parameters are externalized from application logic.
• Ecosystem Compatibility: Seamless integration into established AI application stacks such as LangChain and FastAPI environments with minimal prerequisite setup.
• Adaptable Architecture: Features an extensible framework supporting custom tooling and prompt enhancements tailored to specific domain requirements.

This solution targets developers building intelligent agents that require reliable, context-aware database interaction, significantly mitigating the overhead associated with managing diverse database connectivity layers.

Key Capabilities

• Broad compatibility across numerous relational database platforms.
• Data interaction mediated exclusively through the Legion Query Runner framework.
• Full adoption of MCP standards for tool and resource exposure.
• Database operations mapped directly to MCP resources, tools, and conversational prompts.
• Flexible deployment models (standalone service, embedded FastAPI component).
• Comprehensive query execution, result formatting, and state management.
• Configuration flexibility via environment variables, CLI flags, or structured MCP settings.
• Explicit user control over which datastore is targeted in multi-DB environments.

Supported Data Sources

Database System	Connector Identifier (DB_TYPE)
PostgreSQL	pg
Amazon Redshift	redshift
CockroachDB	cockroach
MySQL	mysql
Amazon RDS MySQL	rds_mysql
MS SQL Server	mssql
Google BigQuery	bigquery
Oracle DB	oracle
SQLite	sqlite

Connectivity is powered by the Legion Query Runner library. Detailed specifications for individual connectors are available in the official API documentation.

Understanding MCP Context Provisioning

The Model Context Protocol (MCP) defines how context is managed in intelligent applications. This server leverages the MCP Python SDK to:

• Expose relational database functions as consumable tools for AI agents.
• Inject database structure (metadata, schemas) as accessible resources.
• Generate contextually relevant instructional prompts for data manipulation.
• Maintain persistent session state when interacting with connected data stores.

Setup and Configuration Directives

Essential Parameters

For deployments connected to a single data source: * DB_TYPE: Specifies the database type code (refer to the table above). * DB_CONFIG: A JSON string containing the necessary connection parameters.

For deployments managing multiple data sources: * DB_CONFIGS: A JSON array where each element defines a separate database instance, including: * db_type: The connector identifier. * configuration: The specific connection parameters. * description: A human-friendly label for the connection.

Connection parameter formats are database-dependent; consult the API documentation for specifics.

Installation Modalities

Method 1: Using UV (Preferred)

When utilizing uv, installation defaults to direct execution via uvx.

UV Configuration Example (Single DB):

REPLACE DB_TYPE and DB_CONFIG with your connection info. { "mcpServers": { "database-mcp": { "command": "uvx", "args": [ "database-mcp" ], "env": { "DB_TYPE": "pg", "DB_CONFIG": "{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"dbname\"}" }, "disabled": true, "autoApprove": [] } } }

UV Configuration Example (Multi-DB):

{ "mcpServers": { "database-mcp": { "command": "uvx", "args": [ "database-mcp" ], "env": { "DB_CONFIGS": "[{\"id\":\"pg_main\",\"db_type\":\"pg\",\"configuration\":{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"postgres\"},\"description\":\"PostgreSQL Database\"},{\"id\":\"mysql_data\",\"db_type\":\"mysql\",\"configuration\":{\"host\":\"localhost\",\"port\":3306,\"user\":\"root\",\"password\":\"pass\",\"database\":\"mysql\"},\"description\":\"MySQL Database\"}]" }, "disabled": true, "autoApprove": [] } } }

Method 2: Using PIP

Installation via standard Python package manager:

bash pip install database-mcp

PIP Configuration Example (Single DB):

{ "mcpServers": { "database": { "command": "python", "args": [ "-m", "database_mcp", "--repository", "path/to/git/repo" ], "env": { "DB_TYPE": "pg", "DB_CONFIG": "{\"host\":\"localhost\",\"port\":5432,\"user\":\"user\",\"password\":\"pw\",\"dbname\":\"dbname\"}" } } } }

Launching the Service

Standard Execution Mode

bash python mcp_server.py

Configuration Methods Overview

Environment Variables (Single Database Context)

bash export DB_TYPE="pg" export DB_CONFIG='{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}' uv run src/database_mcp/mcp_server.py

Environment Variables (Multi-Database Context)

bash export DB_CONFIGS='[{"id":"pg_main","db_type":"pg","configuration":{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"},"description":"PostgreSQL Database"},{"id":"mysql_users","db_type":"mysql","configuration":{"host":"localhost","port":3306,"user":"root","password":"pass","database":"mysql"},"description":"MySQL Database"}]' uv run src/database_mcp/mcp_server.py

If database identifiers (id) are omitted from DB_CONFIGS, the system automatically assigns identifiers derived from the db_type and the entry's position (e.g., "pg_postgres_0").

Command Line Arguments (Single Database Context)

bash python mcp_server.py --db-type pg --db-config '{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}'

Command Line Arguments (Multiple Databases Context)

bash python mcp_server.py --db-configs '[{"id":"pg_main","db_type":"pg","configuration":{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"},"description":"PostgreSQL Database"},{"id":"mysql_users","db_type":"mysql","configuration":{"host":"localhost","port":3306,"user":"root","password":"pass","database":"mysql"},"description":"MySQL Database"}]'

Explicit database IDs can be supplied in the --db-configs payload, otherwise, default unique identifiers are synthesized.

Managing Multiple Data Stores

When operating in a multi-database environment, precise targeting of operations is mandatory:

1. Invoke the list_databases utility to obtain the set of available connection IDs.
2. Utilize get_database_info to inspect the structure of any specific datastore.
3. Employ find_table for locating structures across the entire connected pool.
4. Include the mandatory db_id argument in tools such as execute_query, get_table_columns, etc.

Internally, connections are managed as a collection of DbConfig structures indexed by their unique IDs. Schema representation utilizes a standardized hierarchy of table objects, each containing column metadata. The select_database prompt is provided to assist users interactively in selecting the correct target context.

Internal Schema Object Structure

Database structures are serialized as an array of table definitions, detailing column names and types:

[ { "name": "users", "columns": [ {"name": "id", "type": "integer"}, {"name": "username", "type": "varchar"}, {"name": "email", "type": "varchar"} ] }, { "name": "orders", "columns": [ {"name": "id", "type": "integer"}, {"name": "user_id", "type": "integer"}, {"name": "product_id", "type": "integer"}, {"name": "quantity", "type": "integer"} ] } ]

This canonical structure ensures consistent programmatic access to schema elements.

MCP Exposed Interfaces

Resources

Endpoint	Purpose
resource://schema/{database_id}	Retrieves the schema definitions for a specified database, or all if omitted.

Tools

Tool Name	Functionality
execute_query	Runs arbitrary SQL, returning results formatted as a Markdown table.
execute_query_json	Executes SQL, returning results serialized in JSON format.
get_table_columns	Fetches the field names for a designated table.
get_table_types	Retrieves the data types assigned to table columns.
get_query_history	Accesses the log of recently executed queries.
list_databases	Enumerates all currently established database connections.
get_database_info	Provides comprehensive structural metadata for a database.
find_table	Locates a specified table across all connected data sources.
describe_table	Offers detailed metadata covering column names and types for a table.
get_table_sample	Retrieves a small subset of records from a specified table.

All data manipulation tools necessitate the inclusion of the db_id argument to specify the execution target.

Prompts

Prompt Handler	Operation Description
sql_query	Guides the construction of SQL statements against the active database context.
explain_query	Provides a breakdown of the intended actions of a given SQL statement.
optimize_query	Suggests modifications to improve SQL execution efficiency.
select_database	Facilitates the user in choosing the correct underlying data repository.

Development Workflow

Leveraging the MCP Inspector

Start the inspector environment: bash npx @modelcontextprotocol/inspector uv run src/database_mcp/mcp_server.py

Use the command input field to launch with specific parameters, e.g.:

run src/database_mcp/mcp_server.py --db-type pg --db-config '{"host":"localhost","port":5432,"user":"username","password":"password","dbname":"database_name"}'

Testing Procedures

Install development dependencies and run tests: bash uv pip install -e ".[dev]" pytest

Distribution and Publishing

Standard build and deployment steps: bash

Artifact cleanup

rm -rf dist/ build/

Prune egg-info directories if present

find . -name "*.egg-info" -type d -exec rm -rf {} + 2>/dev/null || true

Package creation

uv run python -m build

Upload to repository

uv run python -m twine upload dist/*

Licensing Information

This project is distributed under the GPL license.

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface (API) implemented as a JavaScript object, primarily used to facilitate the transmission of HTTP requests from a web browser to a web server. Its methods enable browser-based applications to dispatch network requests post-page load and receive subsequent information asynchronously. XHR is foundational to the programming pattern known as Ajax. Before its widespread adoption, server interaction relied heavily on traditional page refreshes triggered by form submissions or hyperlink navigation.

== Genesis == The underlying concept for XMLHttpRequest was first conceptualized in 2000 by developers associated with Microsoft Outlook. This concept was subsequently actualized within the Internet Explorer 5 browser, released in 1999. However, the initial implementation did not utilize the standardized XMLHttpRequest identifier; instead, it relied on COM object instantiation syntax like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 arrived in 2006, full support for the official XMLHttpRequest identifier had been universally adopted across Microsoft's browser line. Today, XMLHttpRequest stands as the de facto standard across all major browser engines, including Mozilla's Gecko (since 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) issued the first formal Working Draft specification for the XMLHttpRequest object on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing features like progress monitoring, cross-site request handling, and byte stream management. By the conclusion of 2011, the enhancements defined in Level 2 were integrated back into the primary specification document. As of late 2012, the responsibility for maintaining the living specification document, utilizing Web IDL definitions, transitioned to the WHATWG organization.

== Operational Procedure == Executing a network request using XMLHttpRequest generally necessitates adherence to several sequential programming steps:

1. Instantiate the required XMLHttpRequest object via its constructor:
2. Invoke the open method to delineate the request method (GET/POST), specify the target Uniform Resource Identifier (URI), and select either synchronous or asynchronous execution mode:
3. For asynchronous operations, register a callback function to process the object's state changes:
4. Commence the transmission by calling the send method:
5. The application must monitor the object's state transitions within the registered listener. Upon successful receipt of the server's payload, the data is typically available in the responseText attribute. When processing concludes, the object transitions to state 4, designated as the "done" state. Beyond these fundamental steps, XHR offers extensive customization for request control and response parsing. Custom HTTP headers can be affixed to modify server behavior, and data payloads can be passed to the send call for server-side reception. Responses can be parsed directly from JSON into native JavaScript objects or streamed incrementally rather than waiting for the complete message body. Furthermore, requests can be terminated prematurely or configured with timeouts to enforce completion deadlines.

== Cross-Origin Communication ==

In the nascent stages of the World Wide Web, security restrictions made it virtually impossible to initiate requests across different security domains. This limitation, rooted in the same-origin policy, restricted the scope of client-side data fetching. The evolution of XHR Level 2 began to address this by introducing mechanisms like CORS (Cross-Origin Resource Sharing) headers, allowing explicit, secure delegation of access rights from the target server to the originating domain.