ValkDB MCP Server — Connect MCP-compatible agents to PostgreSQL through ValkDB

What it does

A small, focused bridge between MCP clients and ValkDB's session control engine.

Exposes ValkDB to MCP-compatible agents over the standard stdio transport.
Lets agents run read-only PostgreSQL queries through ValkDB, never directly.
Injects agent_id and session_id server-side so the agent can't spoof another identity or reset its own budget.
Applies session budgets and circuit breaker behavior across the whole conversation, not just per request.
Provides schema discovery through valk_schema. Sensitive columns (password, token, secret, api_key, card_number) are stripped server-side.
Provides audit visibility through valk_audit when VALKDB_AUDIT_ENABLED=true.
Keeps PostgreSQL credentials out of the agent's context entirely.

What it does NOT do

Honest scope. ValkDB MCP is a thin, focused layer in v0.1.

Does not replace PostgreSQL.
Does not replace your backend.
Does not give database credentials to agents.
Does not support writes in v0.1. Only read-only SELECT is accepted; the in-process Read_Only_Guard blocks anything else before any HTTP call.
Does not remove SQL in v0.1. The agent still sends SQL; ValkDB validates and enforces it.
Does not provide a hosted multi-DB enterprise remote MCP yet.
Does not make production usage safe without operator review.
Does not promise Orbital, multi-region, or full multi-tenant SLAs in this release.

Status

Technical preview. Use it on staging, synthetic, or disposable databases first.

Transport

Local stdio MCP (no network listener required on the client side)

Database

PostgreSQL first. Other engines later.

Query mode

Read-only (SELECT) only. Multi-statement payloads rejected.

Budgets

ValkDB session budgets (rows, queries, window) enforced server-side

Audit

Hash-only. Raw SQL not stored. valk_audit tool gated by env var.

Compatibility

Claude Desktop, Cursor, Kiro, any MCP client over stdio

Distribution

npm package @valkdb/mcp-server prepared but not the primary install path yet

Recommended first use

Local test DB · fake data · staging · disposable Postgres

Install / Try locally

The MCP preview is distributed as a downloadable source tarball, with the same source mirrored at github.com/Valkdb-dev/valkdb. npm publication is held back on purpose until v0.1 is signed off by early users.

1. Download and run from the tarball

curl -LO https://valkdb.dev/downloads/valkdb-mcp-server-0.1.0.tar.gz
tar -xzf valkdb-mcp-server-0.1.0.tar.gz
cd valkdb-mcp-server
npm ci
npm run build
node dist/index.js   # smoke check; the process will exit with a clear error
                     # listing the missing env vars below

Verify the download checksum against downloads/valkdb-mcp-server-0.1.0.SHA256 if your environment requires it.

The downloadable preview package is optimized for local evaluation. The public repository includes tests and development assets.

2. Make it available to MCP clients

Either point clients at the absolute path to dist/index.js (recommended for the preview), or link it as a global valkdb-mcp binary:

npm link              # registers ./dist/index.js as `valkdb-mcp` on PATH
which valkdb-mcp      # confirm

3. Required environment

Variable	Required	Description
`VALKDB_API_URL`	yes	Base URL of your ValkDB deployment (e.g. `http://localhost:8081` for the local preview)
`VALKDB_API_KEY`	yes	Bearer token issued by your ValkDB instance
`VALKDB_AGENT_ID`	yes	Stable identifier for the agent. Used for budget scoping.
`VALKDB_DEFAULT_DATABASE`	no	Connection name or UUID. Defaults to `main`.
`VALKDB_AUDIT_ENABLED`	no	`"true"` to expose the `valk_audit` tool. Defaults to `"false"`.
`VALKDB_SESSION_MODE`	no	Only `per_process` in v0.1.

When npx -y @valkdb/mcp-server becomes the official path, the same env vars apply, only the launch command changes.

Configure your MCP client

Each client expects an absolute path to dist/index.js while the package is unpublished.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "valkdb": {
      "command": "node",
      "args": ["/absolute/path/to/supersonic/valkdb-mcp-server/dist/index.js"],
      "env": {
        "VALKDB_API_URL": "http://localhost:8081",
        "VALKDB_API_KEY": "sk-supersonic-...",
        "VALKDB_AGENT_ID": "claude-desktop-1"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for user-level).

{
  "mcpServers": {
    "valkdb": {
      "command": "node",
      "args": ["/absolute/path/to/supersonic/valkdb-mcp-server/dist/index.js"],
      "env": {
        "VALKDB_API_URL": "http://localhost:8081",
        "VALKDB_API_KEY": "sk-supersonic-...",
        "VALKDB_AGENT_ID": "cursor-1"
      }
    }
  }
}

Kiro

Add to ~/.kiro/settings/mcp.json (user) or .kiro/settings/mcp.json (workspace).

{
  "mcpServers": {
    "valkdb": {
      "command": "node",
      "args": ["/absolute/path/to/supersonic/valkdb-mcp-server/dist/index.js"],
      "env": {
        "VALKDB_API_URL": "http://localhost:8081",
        "VALKDB_API_KEY": "sk-supersonic-...",
        "VALKDB_AGENT_ID": "kiro-1"
      },
      "disabled": false,
      "autoApprove": ["valk_budget", "valk_schema"]
    }
  }
}

Tip: keep valk_query and valk_audit out of autoApprove while you are still validating the setup. Approve them by hand the first few times.

Tools exposed

Four tools. Closed input schemas. Server-side identity injection.

`valk_query`

Run a single read-only SELECT. Anything else (DML, DDL, multi-statement, EXECUTE, CALL) is rejected before the upstream call.

{ "query": "SELECT id, email FROM users WHERE active = true", "max_rows": 100 }
↓
{ "ok": true, "data": { "rows": [...], "row_count": 2 } }

`valk_budget`

Inspect remaining session capacity at any time. No input fields.

{} ↓
{ "status": "active",
  "queries": { "used": 3, "limit": 10 },
  "rows":    { "used": 120, "limit": 5000 },
  "window":  { "remaining_seconds": 47 } }

`valk_schema`

List tables and columns visible to the agent. Sensitive columns are stripped server-side, twice — once upstream, once by the MCP server.

{ "database": "main" } ↓
{ "database": "main",
  "tables": [
    { "name": "users",
      "columns": [
        { "name": "id",     "type": "integer" },
        { "name": "email",  "type": "text"    }
      ] }
  ] }

`valk_audit`

Recent audit events for the running session. Only registered when VALKDB_AUDIT_ENABLED=true; otherwise the tool returns PERMISSION_DENIED.

{ "limit": 5 } ↓
[ { "ts": "2026-05-25T12:00:00Z", "tool": "valk_query", "decision": "allowed" },
  { "ts": "2026-05-25T12:00:05Z", "tool": "valk_query", "decision": "blocked",
    "reason": "session_query_limit_exceeded" } ]

Security model

The server is the trust boundary between the agent and the database.

Identity is server-side. agent_id is read once at startup; session_id is generated as a fresh UUID v4 per process. Both overwrite anything an agent tries to send. Inbound agent_id/session_id/task_id properties are stripped before forwarding.
Read-only enforced before the wire. Every valk_query SQL string is parsed and rejected if it is empty, does not begin with SELECT, contains a forbidden keyword (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, EXECUTE, CALL), contains a multi-statement separator, or exceeds 8192 characters.
No DB credentials in the agent. The PostgreSQL connection string lives only in ValkDB. The agent only sees structured tool responses or the standard error envelope.
Sensitive columns are scrubbed twice. Names matching password, card_number, token, secret, api_key (case-insensitive, after trimming) are stripped from valk_schema responses, regardless of what the upstream API returns.
Errors don't leak. Error envelopes never embed the API key, the API URL host, or stack traces. Verified by adversarial tests in the package's test suite.
Budgets enforced upstream. ValkDB owns the session budget. Reconnects from the same agent_id + session_id continue consuming the same budget, they don't reset it.
Audit is opt-in. The valk_audit tool is only registered when VALKDB_AUDIT_ENABLED=true. Otherwise it returns PERMISSION_DENIED.

Background: 256 unit + property + integration tests pass. 22 adversarial tests (identity spoofing, SQL mutations, multi-statement, leakage, audit gating) pass. The detailed validation report (VALIDATION_REPORT.md) ships with the source tarball.

Known limitations in v0.1

If any of these are blockers for your use case, tell us. They're prioritized by real demand.

Only PostgreSQL. Other databases (MySQL, Snowflake, BigQuery) are not supported.
Read-only. No INSERT / UPDATE / DELETE path in this release.
session_id is per-process. If the agent restarts, a new session starts. Persisting sessions across restarts is on the roadmap.
The intent engine layer still has open vectors against complex sensitive-column joins. They are tracked internally and were not introduced by the MCP layer, but operators should be aware.
npm package is built and dry-run-clean but is intentionally not published yet. Install from source for now.
No hosted multi-tenant remote MCP. Run it locally and point it at your own ValkDB.

Technical preview — not production-ready without operator review

ValkDB MCP v0.1 is built for technical evaluation. Run it against synthetic data, staging, or a disposable Postgres before pointing it at anything real.

If you're a backend, security, or platform engineer evaluating it for a real workload: please talk to us first. The product is honest about what it does and doesn't do — we'd rather have that conversation up front than ship into surprise.

Try it locally and tell us what breaks

We're not selling ValkDB yet. We're looking for technical users to run the MCP locally and tell us whether the problem is real for them.

Download MCP preview tarball View on GitHub Run the local preview Give technical feedback

Technical feedback: feedback@valkdb.dev