Naxas MCP Server

Open-source, self-hostable PostgreSQL MCP gateway for VS Code Codex and other MCP clients.

It is designed around one rule: read by default; controlled writes only when the owner enables project and user access and the database role permits them.

The current scope is one gateway, multiple databases, multiple users, VS Code Codex, and owner-managed project policy. A ChatGPT custom app is outside the planned workflow.

Why this exists

A single deployment can safely expose multiple PostgreSQL projects without accepting arbitrary database URLs from tool calls. Projects are configured only on the server through PROJECTS_JSON.

Example:

{
  "naxas": { "url": "postgresql://gateway_user:***@postgres:5432/naxas" },
  "another_app": { "url": "postgresql://gateway_user:***@postgres:5432/another_app" }
}

New projects start in Read only mode. Use the owner dashboard's project and user mode dropdowns (Disabled, Read only, Read + Write) and Save buttons; DELETE and maximum write rows are separate controls. Policy changes persist in MCP_ACCESS_FILE; database connections still come only from server environment. With one url, the database role must allow writes for Write to succeed. Existing readUrl / writeUrl settings remain supported.

Tools

| Tool | Purpose | Recommended client policy | | --- | --- | --- | | db_read | SELECT / WITH / EXPLAIN | Read without write permission | | db_schema | Inspect schema metadata | Read without write permission | | db_write_preview | Non-executing EXPLAIN for a proposed write | Read/preview | | db_write | One INSERT / UPDATE / DELETE | Ask for explicit confirmation |

The server blocks DDL, role/privilege changes, COPY, transaction-control statements, and multiple write statements.

Recommended write flow: inspect with db_read → preview with db_write_preview → ask the user for approval → execute with db_write → verify with db_read.

Security model

Security is layered:

1. MCP client permission/confirmation.
2. Server-side project allowlist.
3. SQL policy enforcement.
4. PostgreSQL role privileges; optional separate read/write roles.
5. PostgreSQL privileges remain the final authority.
6. Query and lock timeouts.
7. Structured audit events with request IDs.
8. HTTP rate limiting and request-size limits.
9. Per-project write enablement, DELETE opt-in, and max-row rollback guards.

Do not grant the writer role superuser, owner, schema-management, or role-management capabilities.

Install with npm

Users can run:

npx naxas-mcp init

or install globally:

npm install -g naxas-mcp
naxas-mcp init

Recommended first-run flow:

naxas-mcp init
# edit .env and replace the database password placeholder
naxas-mcp doctor
naxas-mcp start

CLI commands:

| Command | Purpose | | --- | --- | | naxas-mcp init | Create a safe read-only .env template and strong MCP token | | naxas-mcp doctor | Validate config and test PostgreSQL read connectivity | | naxas-mcp generate-token | Generate a secure bearer token | | naxas-mcp generate-user-token | Generate a user token and SHA-256 hash for legacy env setup | | naxas-mcp start | Start the MCP gateway | | naxas-mcp help | Show CLI help |

init intentionally does not collect the database password interactively. It writes a placeholder so the real password can be added directly to a local .env or a deployment secret store such as Coolify.

Quick start

cp .env.example .env
# Edit .env with strong credentials and PROJECTS_JSON
docker compose up --build

Health and readiness checks:

GET http://127.0.0.1:3000/health
GET http://127.0.0.1:3000/ready

Admin dashboard:

GET https://your-domain.example/

The dashboard requires the MCP bearer token before operational data is displayed.

Remote MCP endpoint:

POST https://your-domain.example/mcp

See project scope, Coolify deployment, admin dashboard, VS Code Codex setup, multi-user access, localhost setup, and npm release. Initial Naxas rollout and ChatGPT connection remain as historical/optional references.

Development checks

npm install
npm run check

This runs strict TypeScript checking, tests, a production build, and CLI help smoke test.

PostgreSQL roles

sql/postgres-roles.sql contains a conservative starting point. Customize database name, credentials, and table-level writer grants before running it.

For public deployments, create your own roles rather than reusing the application owner/admin account.

Open source

Licensed under the MIT License. You can fork, self-host, modify, and redistribute this project subject to the license terms.

Current maturity

Version 1.0 covers the documented multi-project, multi-user gateway and owner-managed access controls. Production operators remain responsible for PostgreSQL privileges, secrets, network isolation, backups, and MCP client permissions. See version 1.0 release notes.