@valv/mcp

@valv/mcp

Point it at a database URL. Your agent queries it safely. No SQL, no code.

A zero-config MCP server built on valv. Give it a connection string and it introspects your live schema, serves four tools (list_resources, search_resources, describe_resource, query) read-only by default, and enforces your policies — no SQL ever reaches the model, and it can only read what you allow.

Works with any Prisma-supported database (PostgreSQL, MySQL, SQLite, CockroachDB) and ClickHouse.

Guided setup

The fastest way in — it probes your database, lets you choose access, and writes the config:

npx @valv/mcp init

It prompts for a connection string, confirms the dialect, connects and shows your tables, then offers read-only / pick-tables / a policy-file stub — and writes the .mcp.json entry for you.

Manual setup

Add it to your .mcp.json (or Claude Desktop config):

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@valv/mcp"],
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }
    }
  }
}

For ClickHouse, use its HTTP URL and a database name:

"env": { "DATABASE_URL": "http://localhost:8123", "VALV_DATABASE": "analytics" }

Configuration

All via environment variables:

Variable	Description
DATABASE_URL	Connection string (required; or pass as the first CLI arg).
VALV_PROVIDER	postgresql | mysql | sqlite | clickhouse. Inferred from the URL when omitted.
VALV_DATABASE	Database name (ClickHouse).
VALV_TABLES	Comma-separated allow-list — only these tables are exposed.
VALV_EXCLUDE	Comma-separated deny-list, applied after the allow-list.
VALV_POLICY_FILE	Path to a policy module (below) for tenant scoping / hidden fields.
VALV_CONTEXT	JSON context the policy reads (e.g. {"tenant":{"id":"acme"}}).
VALV_HTTP_PORT	Serve over Streamable HTTP on this port instead of stdio.

Policy file

Without one, access is read-only across all tables. To restrict what the agent can see — which tables, which columns — point VALV_POLICY_FILE at a module that receives the configured valv instance:

// valv.policy.cjs
module.exports = (valv) => {
  valv.policy("orders", () => ({
    read:   true,                          // allow reads (or { column: value } to filter rows)
    fields: { deny: ["internal_notes"] },  // hide columns from the agent
  }))
  // Tables without a policy are denied (deny-all).
}

Need per-request row scoping by tenant/user? That belongs in the app-controlled path, where your code supplies real identity per request — use @valv/mcp-sdk (or pass a fixed VALV_CONTEXT and read it in the policy here).

License

MIT