mcp-enterprise-starter

mcp-enterprise-starter

A production-grade MCP (Model Context Protocol) server that gives AI agents safe, authenticated access to a PostgreSQL database. Built as a reference implementation for teams building custom MCP servers for enterprise workflows.

Architecture

┌─────────────────┐     ┌──────────────────────────────────┐     ┌────────────┐
│  Claude Desktop  │     │       MCP Enterprise Server       │     │            │
│  VS Code         │────▶│                                  │────▶│ PostgreSQL │
│  Any MCP Client  │     │  Auth → Validation → Tool Logic  │     │            │
└─────────────────┘     └──────────────────────────────────┘     └────────────┘

Security layers:

• API key authentication on every request
• SQL query sandboxing (SELECT only, keyword blocklist)
• Parameterized queries (no SQL injection)
• Sensitive column masking (email, SSN)
• Row limit enforcement
• Per-key rate limiting
• Structured JSON audit logging

Quick Start

Option 1: Docker Compose (recommended)

git clone https://github.com/agrgroup/mcp-enterprise-starter.git
cd mcp-enterprise-starter
cp .env.example .env
docker compose up --build

PostgreSQL starts with seeded sample data. The MCP server connects automatically.

Option 2: Local Development

git clone https://github.com/agrgroup/mcp-enterprise-starter.git
cd mcp-enterprise-starter
npm install
cp .env.example .env

# Start PostgreSQL separately, then seed it:
psql $DATABASE_URL < seed.sql

# Run the server
npm run dev

Connect Claude Desktop

Copy the Claude Desktop config from mcp-config.json into your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "enterprise-db": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/mcp-enterprise-starter",
      "env": {
        "DATABASE_URL": "postgres://mcp_user:mcp_password@localhost:5432/mcp_enterprise",
        "API_KEYS": "your-api-key",
        "ALLOWED_TABLES": "departments,users,projects",
        "SENSITIVE_COLUMNS": "email,ssn"
      }
    }
  }
}

Restart Claude Desktop. Ask: "What tables are available?" to verify the connection.

Connect VS Code

Add to your .vscode/settings.json or user settings:

{
  "mcp": {
    "servers": {
      "enterprise-db": {
        "command": "node",
        "args": ["dist/server.js"],
        "cwd": "${workspaceFolder}/../mcp-enterprise-starter",
        "env": {
          "DATABASE_URL": "postgres://mcp_user:mcp_password@localhost:5432/mcp_enterprise",
          "API_KEYS": "your-api-key",
          "ALLOWED_TABLES": "departments,users,projects",
          "SENSITIVE_COLUMNS": "email,ssn"
        }
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | query_database | Execute read-only SQL queries with automatic row limiting and sensitive column masking | | list_tables | List all tables available for querying (from the configured allowlist) | | get_schema | Get column definitions, types, and constraints for a specific table |

Resources

| URI Pattern | Description | |-------------|-------------| | db://schema/{table_name} | Table schema as structured JSON |

Configuration

| Variable | Default | Description | |----------|---------|-------------| | DATABASE_URL | — | PostgreSQL connection string | | API_KEYS | — | Comma-separated list of valid API keys | | ALLOWED_TABLES | departments,users,projects | Tables the agent can access | | SENSITIVE_COLUMNS | email,ssn | Columns to mask in query results | | ROW_LIMIT | 100 | Default row limit for queries | | MAX_ROW_LIMIT | 1000 | Maximum row limit (even if query specifies higher) | | RATE_LIMIT_RPM | 60 | Requests per minute per API key | | MCP_TRANSPORT | stdio | Transport mode: stdio or sse | | LOG_LEVEL | info | Logging level |

Testing

npm test          # Run all tests
npm run test:watch  # Watch mode

Tests mock the PostgreSQL connection so no database is needed.

Adapt for Your Own Database

1. Update ALLOWED_TABLES in .env to expose your tables
2. Update SENSITIVE_COLUMNS to mask your sensitive fields
3. Update seed.sql with your schema (or remove it and use an existing database)
4. Add new tools in src/tools/ following the pattern in query-database.ts
5. Update src/server.ts to register your new tools
6. Add write operations cautiously — start read-only, add writes with explicit confirmation patterns

Security Notes

• API keys are checked on every tool call. No key = no access.
• Only SELECT queries are allowed. DROP, DELETE, INSERT, UPDATE, and other write operations are blocked at the query level.
• Sensitive columns are masked before results reach the agent. The agent never sees raw PII.
• Row limits prevent accidental full-table scans on large tables.
• All requests are logged as structured JSON to stderr for audit trails.
• The production Docker image runs as a non-root user.

License

MIT