MCP Data Gateway Service

This service implements the Model Context Protocol (MCP) for standardized connectivity and operational management across heterogeneous database systems.

Supported Data Stores

• SQLite
• PostgreSQL
• Microsoft SQL Server
• MongoDB

Deployment

Install globally via npm:

npm install -g mcp-dbs

Execution Modes

The Data Gateway supports dual operational paradigms:

Server-Sent Events (SSE) Mode (Default)

Launches the service in SSE mode, typically binding to port 3001:

npx mcp-dbs

The primary SSE communication channel is exposed at http://localhost:3001/mcp.

Specifying Alternative Port

Override the default networking port with the --port flag:

npx mcp-dbs --port 8080

Standard I/O (STDIO) Mode

For environments requiring piping communication, use the --stdio flag for I/O redirection:

npx mcp-dbs --stdio

Integration with Claude Desktop Environment

The mcp-data-gateway can be seamlessly incorporated into the Claude Desktop configuration layer.

Configuration Procedure

1. Locate or generate your Claude Desktop configuration file.
2. Inject the service definition into the mcpServers map:

{
  "mcpServers": {
    "mcp-data-gateway": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-dbs/dist/cli.js",
        "--stdio"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://localhost:27017",
        "MCP_MONGODB_DATABASE": "your-database-name"
      }
    }
  }
}

Ensure that environment variables reflect actual database connection parameters.

Implementation Directives

• The execution binary should be invoked via node.
• The args array must contain the absolute path to the entry point script (cli.js).
• Configure necessary environment variables corresponding to your chosen persistence technology (covered in the configuration variables section).
• These environment settings are valid for any supported backend (SQLite, Postgres, MSSQL, Mongo).

Operationalizing with Claude

Upon successful configuration, Claude gains the capability to leverage this service for:

• Establishing persistence layer connections.
• Executing arbitrary data manipulation and retrieval queries.
• Schema discovery and mapping.
• Table and collection management operations.

Exposed MCP Procedures (Tools)

• establish-connection: Initiates a link to the specified data store.
• terminate-connection: Closes an active data link.
• run-query: Executes an operation expected to yield results (SELECT, find).
• run-mutation: Executes an operation that modifies data state (INSERT, UPDATE, DELETE, replace).

Resource Interfaces

• system-schema: Retrieves comprehensive metadata for the connected environment.
• table-metadata: Fetches the structural definition for a designated table/collection.
• list-collections: Returns an inventory of all accessible tables/collections.

Configuration via Environment Variables

Connection parameters take precedence when set as environment variables:

SQLite Configuration

# Pre-execution variable assignment
export MCP_SQLITE_FILENAME="/absolute/path/to/db.db"
export MCP_SQLITE_CREATE_IF_NOT_EXISTS="true"

PostgreSQL Configuration

# Pre-execution variable assignment
export MCP_POSTGRES_HOST="pg.example.com"
export MCP_POSTGRES_PORT="5432"
export MCP_POSTGRES_DATABASE="production_db"
export MCP_POSTGRES_USER="app_user"
export MCP_POSTGRES_PASSWORD="secure_pwd"
export MCP_POSTGRES_SSL="false"

SQL Server Configuration

# Pre-execution variable assignment
export MCP_MSSQL_SERVER="sql.corp.net"
export MCP_MSSQL_PORT="1433"
export MCP_MSSQL_DATABASE="main_data_warehouse"
export MCP_MSSQL_USER="admin_svc"
export MCP_MSSQL_PASSWORD="topsecret"
export MCP_MSSQL_ENCRYPT="true"
export MCP_MSSQL_TRUST_SERVER_CERTIFICATE="true"

MongoDB Configuration

# Pre-execution variable assignment
export MCP_MONGODB_URI="mongodb://mongo.internal:27017/"
export MCP_MONGODB_DATABASE="app_data_store"
export MCP_MONGODB_MAX_POOL_SIZE="20"
export MCP_MONGODB_USE_UNIFIED_TOPOLOGY="true"

These variables override runtime settings provided to the establish-connection tool.

MCP Tool Signatures

The service exports the following standardized MCP operations:

establish-connection

Registers and activates a connection handle.

Arguments: * connectionId: A distinct identifier for this session. * type: The underlying database type (sqlite, postgres, mssql, or mongodb).

Example for Postgres Connection:

{
  "connectionId": "finance_staging",
  "type": "postgres"
}

terminate-connection

Shuts down an active connection.

Arguments: * connectionId: The session identifier to release.

run-query

Executes declarative commands yielding result sets.

Arguments: * connectionId: The active connection handle. * query: The directive (SQL string or MongoDB pipeline serialized as JSON). * params: (Optional) Positional/indexed arguments. For MongoDB, the initial element specifies the target collection name.

Example for SQL Query:

{
  "connectionId": "finance_staging",
  "query": "SELECT user_id, balance FROM accounts WHERE region = $1",
  "params": ["EU_WEST"]
}

Example for MongoDB Aggregation:

{
  "connectionId": "mongo_prod",
  "query": "[{\"$match\": {\"status\": \"active\"}}, {\"$project\": {\"_id\": 0, \"name\": 1}} ]",
  "params": ["user_profiles"]
}

run-mutation

Submits imperative commands that modify state (non-result producing).

Arguments: * connectionId: The active connection handle. * query: The command string (SQL DML or MongoDB operation object). * params: (Optional) Parameters for the command; first element for MongoDB is often the collection name.

Example for SQL Insertion:

{
  "connectionId": "finance_staging",
  "query": "INSERT INTO logs (event, timestamp) VALUES ($1, NOW())",
  "params": ["System Check Complete"]
}

Example for MongoDB InsertOne:

{
  "connectionId": "mongo_prod",
  "query": "{\"insertOne\": {\"name\": \"New Client\", \"status\": \"pending\"}}",
  "params": ["client_records"]
}

MCP Metadata Access

The service provides standardized resource URIs for schema retrieval:

Database Structure Summary

URI: data-source://{connectionId}/metadata/structure

Returns comprehensive metadata outlining all accessible entities.

Entity Definition

URI: data-source://{connectionId}/metadata/entities/{entityName}

Retrieves the detailed structure for a specific table or collection.

Entity Inventory

URI: data-source://{connectionId}/metadata/entities

Yields a catalog of all existing entities within the connection scope.

Project Lifecycle

Quality Assurance

Execute the integrated test suite:

npm test

Project Patronage

Support the ongoing development efforts by contributing:

Scan the accompanying Quick Response code or follow this link to offer financial encouragement.

Licensing

MIT License