schemabrain serve

Run the MCP server on stdio against the local store. Exposes the 12 typed MCP tools, writes one audit row per call, optionally enforces the PII policy.

schemabrain serve

Boots the MCP server. Speaks stdio (the protocol Claude Desktop, Cursor, Windsurf, Claude Code, and the Anthropic SDK demo all use). Reads the local SQLite store; never writes back to the source Postgres.

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db

Every tool call writes exactly one row to the mcp_audit table — see Audit chain. When --pii-block is configured, calls that would touch a blocked category return a refused envelope (see Structured recovery).

---

Source

One of these is required:

Flag	Purpose
--url-env VARNAME	Env var holding the source URL. Preferred.
--source URL	Source URL as a named flag. Deprecated when the URL contains a password.

Storage

Flag	Default	Purpose
--store-path PATH	./schemabrain.db	Path to the local SQLite store.

Events

Flag	Default	Purpose
--events-path PATH	$SCHEMABRAIN_EVENTS_PATH or ~/.schemabrain/events.jsonl	Path to the JSONL events file the bus appends to. Read with schemabrain tail.
--no-events	(off)	Disable event emission entirely. No JSONL file is written; no server_start / server_stop events. Useful for CI.

Audit

Flag	Effect
--no-audit	Disable the mcp_audit table writer for this process. Tools still respond; the durable per-call record is suppressed. Use for CI runs or tests where audit writes would clutter a shared store.

PII policy

Flag	Default	Purpose
--pii-block CSV	credential,payment_card,government_id	Comma-separated PIICategory list. When a compiled get_metric plan touches one of these, the call returns refused with refusal_reason='pii_blocked'. Unknown category names abort startup with an error listing the 12 valid values. Pass '' (empty) to clear the operator policy for this run; the always-on catastrophic-leak floor (credential / payment_card / government_id) still refuses at every read gate and cannot be disabled. PII tags still flow to the audit row.

The default — three catastrophic-leak categories — is the floor every production deployment should keep. Broaden it (contact,health,financial,...) for stricter postures. See PII taxonomy for the full category list.

Query safety

Flag	Default	Purpose
--statement-timeout-ms MS	30000 (30s)	Postgres-level statement_timeout applied to every get_metric query. A runaway query aborts with OperationalError rather than blocking the process pool. Injected into connect_args.options so it cannot be overridden via URL query params. Pass 0 to disable (Postgres treats statement_timeout=0 as unbounded).
--max-rows-per-result N	10000	Application-level cap on rows returned by each get_metric call. Counts after the SQL executes (the source DB still does the full scan) — this is a payload-size guard, not a query-cost guard. Use --statement-timeout-ms for the latter. Pass 0 to disable the cap.

---

How hosts invoke this

You almost never run serve directly in a terminal. Instead, your MCP host (Claude Desktop, Cursor, Windsurf, Claude Code) spawns it as a subprocess and speaks stdio across the pipe. The host’s config file carries the exact argv. The Setup page covers the per-host config blocks.

For verifying the install end-to-end without a host, run examples/anthropic_demo.py (see Manual flow — Anthropic SDK demo).

---

Logging

serve cannot accept -v flags from a host config — there is no command line you control. Use the env-var form instead:

{
  "mcpServers": {
    "schemabrain": {
      "command": "/usr/local/bin/schemabrain",
      "args": ["serve", "--url-env", "DATABASE_URL", "--store-path", "/abs/path/to/store.db"],
      "env": {
        "DATABASE_URL": "postgresql+psycopg://...",
        "SCHEMABRAIN_LOG_LEVEL": "INFO"
      }
    }
  }
}

Valid SCHEMABRAIN_LOG_LEVEL values: DEBUG, INFO, WARNING, ERROR, CRITICAL (case-insensitive). Unknown values fall back to WARNING and emit a one-line warning to stderr.

Output lands in:

• macOS: ~/Library/Logs/Claude/mcp-server-schemabrain.log
• Linux: the equivalent Claude Desktop log path on your platform.

---

Examples

Default policy (recommended)

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db

The three catastrophic-leak categories block automatically.

Strict policy

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db \
    --pii-block credential,payment_card,government_id,contact,health

Tighter runtime budget than the default

Defaults are already safe (30s timeout, 10k row cap). Tighten further for interactive use, where you’d rather see a fast refusal than wait out a slow query:

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db \
    --statement-timeout-ms 5000 \
    --max-rows-per-result 1000

Clear the operator policy for a debug session

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db \
    --pii-block ''

This clears any operator-added categories (e.g. contact, health) so those columns are queryable again. The always-on catastrophic-leak floor (credential / payment_card / government_id) still refuses and cannot be turned off; tags still flow into audit rows regardless.

CI smoke

schemabrain serve --url-env DATABASE_URL --store-path ./schemabrain.db \
    --no-audit --no-events

---

Related

MCP tool reference

The 12 typed tools serve exposes.

PII taxonomy

The 12 categories --pii-block accepts.

schemabrain tail

Stream events from a running serve process.

schemabrain audit

Inspect the mcp_audit table serve writes to.