valv MCP server

valv

Let agents query your database. Just not all of it.

valv gives an agent structured tools to read your database — and, opt-in, to write to it. The model emits a structured query (or insert/update/delete) — never a native database command — and valv validates it against your schema, scopes it to the current user with policies you write in code, compiles it for your database, and runs it.

The model's query is treated as fully untrusted. It can't read a column you hid, a row the user isn't allowed to see, call a function you didn't allow, write a column you didn't permit, or escape its tenant on a write. Valv rebuilds and checks the query on the server before it reaches the database adapter.

const valv = await createValv(client, { schema: "introspect", defaultPolicy: "deny-all" })

valv.policy("orders", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },   // every read is scoped to this tenant
  fields: { deny: ["internal_notes"] },   // this column never reaches the model
}))

const tools = await valv.tools.aisdk(ctx)  // hand to your agent — it queries safely

Two ways to use it

• In your app. Configure valv in code, write policies against your request context, and hand the tools to your agent — Vercel AI SDK, Anthropic, OpenAI, or Gemini. Or expose those same tools over MCP with @valv/mcp-sdk, scoped per request.
• With a coding agent. Point @valv/mcp at a database and a tool like Claude Code queries it safely — no code required.

Quick start

Install an adapter for your database (it pulls in @valv/core):

npm i @valv/clickhouse @clickhouse/client     # ClickHouse
# or
npm i @valv/prisma @prisma/client             # Postgres / MySQL / SQLite
# or
npm i @valv/mongodb mongodb                    # MongoDB

Wire it up — connect, write a policy, hand the tools to an agent:

import { createValv } from "@valv/clickhouse"
import { generateText, stepCountIs } from "ai"

// 1. Connect — introspect the live schema (or pass a hand-defined one).
const valv = await createValv(client, { schema: "introspect", defaultPolicy: "deny-all" })

// 2. Policy — what this caller may read, resolved from your context.
valv.policy("orders", (ctx) => ({ read: { tenant_id: ctx.tenant.id } }))

// 3. Tools — bound to the request's context, formatted for your provider.
const ctx = { user: { id: "u1", role: "analyst" }, tenant: { id: "acme" } }
const { text } = await generateText({
  model,
  system: await valv.instructions(ctx),  // how to drive the tools + the caller's resources
  tools: await valv.tools.aisdk(ctx),
  stopWhen: stepCountIs(6),
  prompt: "What's our revenue per order status this month?",
})

The agent gets four tools — listresources, searchresources, describe_resource, and query — discovers your schema, and runs a query. valv scopes it to acme, compiles it to ClickHouse SQL, runs it, and hands back rows.

What the agent can express

One query tool covers the whole read surface. The grammar is Prisma-idiomatic — a shape models already know cold — and desugars server-side into a checked query:

Shortened. The full README is on GitHub.