# valv

Hooks your agent up to a live database through a connection string. Reads only by default, and your policies decide what it can see.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: valv-dev
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/valv-dev/valv/tree/HEAD/packages/mcp
- Updated: 2026-10-02
- HTML: https://affpapa.org/en/nevibecode/mcp/valv

## What it does

The server takes a database URL, inspects the schema on its own, and exposes four tools to the agent: `list_resources`, `search_resources`, `describe_resource` and `query`. No SQL text ever reaches the model — it goes through those calls instead. PostgreSQL, MySQL, SQLite, CockroachDB, ClickHouse and MongoDB are supported.

Setup runs fastest with `npx @valv/mcp init`. It probes the database, shows your tables, asks which access level you want, then merges the server entry into Claude, Claude Desktop, Cursor or Codex without touching what is already in the config. Doing it by hand means an `mcpServers` block in `.mcp.json` with `DATABASE_URL` under `env`. ClickHouse wants an HTTP URL plus a database name in `VALV_DATABASE`; MongoDB needs `VALV_DATABASE` when the URL does not pick one.

With no policy file, every table is readable. The moment you set `VALV_POLICY_FILE`, tables that have no policy are denied — deny-all. Hiding columns or filtering rows also happens in that module. Per-request scoping by tenant or user does not belong here; your app supplies real identity through `@valv/mcp-sdk`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `DATABASE_URL`, `VALV_PROVIDER`, `VALV_DATABASE`, `VALV_TABLES`, `VALV_EXCLUDE`, `VALV_POLICY_FILE`, `VALV_CONTEXT`, `VALV_HTTP_PORT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env DATABASE_URL=<DATABASE_URL> --env VALV_PROVIDER=<VALV_PROVIDER> --env VALV_DATABASE=<VALV_DATABASE> --env VALV_TABLES=<VALV_TABLES> --env VALV_EXCLUDE=<VALV_EXCLUDE> --transport stdio mcp -- npx -y @valv/mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add mcp --env DATABASE_URL=<DATABASE_URL> --env VALV_PROVIDER=<VALV_PROVIDER> --env VALV_DATABASE=<VALV_DATABASE> --env VALV_TABLES=<VALV_TABLES> --env VALV_EXCLUDE=<VALV_EXCLUDE> -- npx -y @valv/mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@valv/mcp"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>",
                "VALV_PROVIDER": "<VALV_PROVIDER>",
                "VALV_DATABASE": "<VALV_DATABASE>",
                "VALV_TABLES": "<VALV_TABLES>",
                "VALV_EXCLUDE": "<VALV_EXCLUDE>"
            }
        }
    }
}
```
Replace <…> with your own values. 3 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@valv/mcp"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>",
                "VALV_PROVIDER": "<VALV_PROVIDER>",
                "VALV_DATABASE": "<VALV_DATABASE>",
                "VALV_TABLES": "<VALV_TABLES>",
                "VALV_EXCLUDE": "<VALV_EXCLUDE>"
            }
        }
    }
}
```
Replace <…> with your own values. 3 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e DATABASE_URL=<DATABASE_URL> -e VALV_PROVIDER=<VALV_PROVIDER> -e VALV_DATABASE=<VALV_DATABASE> -e VALV_TABLES=<VALV_TABLES> -e VALV_EXCLUDE=<VALV_EXCLUDE> mcp npx -y @valv/mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

## When to use it
- let an agent read a database without handing it SQL access
- expose only chosen tables with the `VALV_TABLES` allow-list
- keep internal columns away from the model via a policy
- wire one database into several editors
- serve the server over HTTP instead of stdio with `VALV_HTTP_PORT`

## Example prompts
- List the tables in this database and describe the `orders` schema
- Find everything in the database related to last month's orders
- Build a `valv-map.html` overview of the database

## Similar
- [whodb](https://affpapa.org/en/nevibecode/plugins/whodb.md) — plugin · ★ 5042
- [optimize-database-performance](https://affpapa.org/en/nevibecode/commands/optimize-database-performance.md) — command · 794 installs
- [database-administrator](https://affpapa.org/en/nevibecode/agents/database-administrator.md) — subagent · 452 installs
- [database-backups](https://affpapa.org/en/nevibecode/skills/database-backups.md) — skill · 405 installs
- [database-optimization](https://affpapa.org/en/nevibecode/agents/database-optimization.md) — subagent · 3924 installs
- [relational-database-mcp-cloudbase](https://affpapa.org/en/nevibecode/skills/relational-database-mcp-cloudbase.md) — skill · 956 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md