How do I install Boyce?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Boyce need an API key?

The publisher lists these environment variables: BOYCE_DB_URL, BOYCE_PROVIDER, ANTHROPIC_API_KEY.

When was Boyce last checked?

Last checked 2026-11-09. Deterministic SQL compiler for AI agents. Your agent stops guessing SQL.

Boyce MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx boyce==0.1.1

Credentials from the publisher

BOYCE_DB_URL — PostgreSQL or Redshift connection string. Optional — tools work without live DB; required for live profiling and EXPLAIN pre-flight.
BOYCE_PROVIDER — LLM provider for the NL→StructuredFilter planner (anthropic, openai). MCP hosts using their own model should not set this — the host's model does the reasoning and Boyce receives a pre-built StructuredFilter.
ANTHROPIC_API_KEY — Required only when BOYCE_PROVIDER=anthropic and the host does not supply its own model. MCP hosts (Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains) do not need this.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1BOYCE_DB_URL=<value> BOYCE_PROVIDER=<value> ANTHROPIC_API_KEY=<value> claude mcp add io.github.boyce-io-boyce -- uvx boyce==0.1.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.boyce-io-boyce": {4      "command": "uvx",5      "args": [6        "boyce==0.1.1"7      ],8      "env": {9        "BOYCE_DB_URL": "<value>",10        "BOYCE_PROVIDER": "<value>",11        "ANTHROPIC_API_KEY": "<value>"12      }13    }14  }15}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Boyce: Semantic Protocol & Safety Layer for Agentic Database Workflows

The semantic safety layer for agentic database workflows. Boyce connects LLMs to live database context with built-in safety rails.

Named for Raymond F. Boyce, co-inventor of SQL (1974) and co-author of Boyce-Codd Normal Form (BCNF).

AI agents querying databases without proper context generate unreliable SQL — working from incomplete schemas, inferring column names, guessing join paths. Boyce gives agents the structured database intelligence they need to generate correct, safe SQL every time — through three interconnected systems:

Layer	What it does
SQL Compiler	`ask_boyce` — NL → StructuredFilter → deterministic SQL. Zero LLM in the SQL builder. Same inputs, same SQL, byte-for-byte, every time.
Database Inspector	`query_database` / `profile_data` — Live Postgres/Redshift adapters let your agent see real schema and real data distributions before writing a single filter.
Query Verification	Pre-flight `EXPLAIN` loops on every generated query. Bad SQL is caught at planning time, not at 2am in your on-call rotation.

Why does this matter? → The Null Trap: Your AI Agent's SQL Is Correct. The Answer Is Still Wrong.

Install

Requires Python 3.10+

pip install boyce

# With live Postgres/Redshift adapter (enables EXPLAIN pre-flight + column profiling)
pip install "boyce[postgres]"

# uv (recommended)
uv pip install boyce
uv pip install "boyce[postgres]"

From source:

git clone https://github.com/boyce-io/boyce
uv pip install -e "boyce/"

Quickstart

After installing, run boyce init to configure your MCP host automatically:

boyce init

The wizard detects Claude Desktop, Cursor, Claude Code, and JetBrains (DataGrip, IntelliJ, etc.), and writes the correct config block for each.

Developing from source? The repo includes a setup script:

./quickstart.sh   # detects uv or python, installs package, writes .env template

Configure Your MCP Host

The fastest path is boyce init — it detects your MCP host and writes the config automatically:

boyce init

Or configure manually. There are two setup paths depending on your host:

Path 1 — MCP Hosts (No LLM key required)

If you're using Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains (DataGrip, IntelliJ), or any MCP-compatible host, you do not need to configure an LLM provider for Boyce. The host's own model handles reasoning — Boyce supplies the schema context and deterministic SQL compiler via get_schema and ask_boyce. Only BOYCE_DB_URL is needed (and even that is optional).

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

Cursor (.cursor/mcp.json in project root):

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

Path 2 — With Boyce's Built-in NL→SQL

If you're using the CLI (boyce ask), HTTP API, or a non-MCP client (e.g., the VS Code extension), configure Boyce's internal query planner with your LLM provider:

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_PROVIDER": "anthropic",
        "BOYCE_MODEL": "claude-sonnet-4-6",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

Boyce supports any LLM provider available through LiteLLM: Anthropic, OpenAI, Ollama (local), vLLM (local), Azure, Bedrock, Vertex, Mistral, and more.

BOYCE_DB_URL is optional on both paths. Without it, Boyce runs in schema-only mode — SQL generation still works; EXPLAIN pre-flight and live query tools return "status": "unchecked".

Environment Variables

Variable	When needed	Example	Purpose
`BOYCE_PROVIDER`	Path 2 only (CLI/HTTP/non-MCP)	`anthropic`	LiteLLM provider name
`BOYCE_MODEL`	Path 2 only (CLI/HTTP/non-MCP)	`claude-sonnet-4-6`	Model ID passed to LiteLLM
`ANTHROPIC_API_KEY`	When using Anthropic	`sk-ant-...`	Anthropic credentials
`OPENAI_API_KEY`	When using OpenAI	`sk-...`	OpenAI credentials
`BOYCE_DB_URL`	Optional (either path)	`postgresql://user:pass@host:5432/db`	asyncpg DSN — enables EXPLAIN pre-flight + live query tools
`BOYCE_HTTP_TOKEN`	Path 2 HTTP API only	`my-secret-token`	Bearer token for `boyce serve --http`
`BOYCE_STATEMENT_TIMEOUT_MS`	Optional	`30000`	Per-statement timeout in ms (default: 30s)

MCP Tools

Tool	Description
`ingest_source`	Parse a `SemanticSnapshot` from dbt manifest, dbt project, LookML, DDL, SQLite, Django, SQLAlchemy, Prisma, CSV, or Parquet.
`ingest_definition`	Store a certified business definition — injected automatically at query time.
`get_schema`	Return full schema context + StructuredFilter format docs. Used by MCP hosts so the host LLM can construct queries without a Boyce API key.
`ask_boyce`	Full NL → SQL pipeline: query planner (LiteLLM) → deterministic kernel → NULL trap check → EXPLAIN pre-flight.
`validate_sql`	Validate hand-written SQL — EXPLAIN pre-flight, Redshift lint, NULL risk — without executing.
`query_database`	Execute a read-only `SELECT` against the live database. Write operations rejected at two independent layers.
`profile_data`	Null %, distinct count, min/max for any column — surface data quality issues before they affect query results.
`check_health`	Operational health check — DB connectivity, snapshot freshness, actionable fix commands. Call when queries fail unexpectedly.

Architecture

SemanticSnapshot (JSON)
        │
        ▼  ingest_source
 ┌─────────────────────────────────────────────┐
 │          SemanticGraph (NetworkX)            │  ← in-memory, loaded per session
 │  nodes = entities (tables/views/dbt models) │
 │  edges = joins  (weighted by confidence)    │
 └─────────────────────────────────────────────┘
        │                         │
        ▼  ask_boyce              ▼  (internal)
  QueryPlanner                 Dijkstra
  (LiteLLM)                    join resolver
  NL → StructuredFilter             │
        │                           │
        └──────────┬────────────────┘
                   ▼
           kernel.process_request()          ← ZERO LLM HERE
           SQLBuilder (dialect-aware)
                   │
                   ▼
           EXPLAIN pre-flight                ← Query Verification
           (PostgresAdapter)
                   │
                   ▼
            SQL + validation result

Dialect support: redshift, postgres, duckdb, bigquery

Redshift safety rails (safety.py): Automatic linting for LATERAL, JSONB, REGEXP_COUNT, lookahead regex patterns, and numeric cast rewrites for Redshift 1.0 (PG 8.0.2).

Scan CLI

# Scan a single file
boyce scan demo/magic_moment/manifest.json

# Scan a directory (auto-detects all parseable sources)
boyce scan ./my-project/ -v

# Save snapshots for MCP server use
boyce scan ./my-project/ --save

10 parsers: dbt manifest, dbt project, LookML, SQLite, DDL, CSV, Parquet, Django, SQLAlchemy, Prisma.

Verify the Install

# Unit tests — no DB required, runs in ~4 seconds
python boyce/tests/verify_eyes.py

# Expected output:
# Ran 15 tests in 3.5s
# OK
# ✅  All checks passed.

SemanticSnapshot Format

The ingest_source tool accepts a SemanticSnapshot JSON dict. Minimal example:

{
  "snapshot_id": "<sha256>",
  "source_system": "dbt",
  "entities": {
    "entity:orders": {
      "id": "entity:orders",
      "name": "orders",
      "schema": "public",
      "fields": ["field:orders:order_id", "field:orders:revenue"]
    }
  },
  "fields": {
    "field:orders:order_id": {
      "id": "field:orders:order_id",
      "entity_id": "entity:orders",
      "name": "order_id",
      "field_type": "ID",
      "data_type": "INTEGER"
    }
  },
  "joins": []
}

See boyce/tests/live_fire/mock_snapshot.json for a complete field/entity example.

Project Layout

boyce/                          ← PRIMARY — headless FastMCP server + pip package
├── boyce/
│   ├── server.py               ← MCP entry point (8 tools)
│   ├── kernel.py               ← Deterministic SQL kernel
│   ├── graph.py                ← SemanticGraph (NetworkX)
│   ├── safety.py               ← Redshift compatibility rails
│   ├── types.py                ← Protocol contract (Pydantic)
│   ├── scan.py                 ← Scan CLI (boyce scan)
│   ├── connections.py          ← DSN persistence (ConnectionStore)
│   ├── doctor.py               ← Environment diagnostics (boyce doctor)
│   ├── sql/                    ← SQLBuilder, dialect layer, join resolver
│   ├── parsers/                ← 10 parsers (dbt, lookml, ddl, sqlite, csv, etc.)
│   ├── planner/                ← QueryPlanner (LiteLLM → StructuredFilter)
│   └── adapters/               ← PostgresAdapter (Eyes)
└── tests/
    ├── verify_eyes.py          ← 15-test suite, no DB required
    ├── test_parsers.py         ← Parser tests (all 10 parsers)
    ├── test_scan.py            ← Scan CLI tests
    └── live_fire/              ← Docker Compose integration tests

Status

Capability	Status
NL → SQL (deterministic kernel)	Operational
SemanticGraph (join resolution)	Operational
10 source parsers	Operational
Scan CLI (`boyce scan`)	Operational
PostgresAdapter (read-only)	Operational
EXPLAIN pre-flight validation	Operational
NULL Trap detection	Operational
Redshift 1.0 safety linting	Operational
Snapshot persistence across restarts	Operational
Audit logging (append-only JSONL)	Operational
Business definitions (`ingest_definition`)	Operational
DSN persistence (`ConnectionStore`)	Operational
Environment diagnostics (`boyce doctor` / `check_health`)	Operational
Multi-snapshot merge	Planned

Support

Troubleshooting guide: docs/troubleshooting.md
Local LLM setup (Ollama/vLLM): docs/local-llm-setup.md
Bug reports: GitHub Issues
Setup help: GitHub Issues
Email: [email protected] — for issues involving credentials or sensitive config

Boyce

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Boyce?

Does Boyce need an API key?

What transport does Boyce use?

When was Boyce last checked?

Documentation

Boyce: Semantic Protocol & Safety Layer for Agentic Database Workflows

Install

Quickstart

Configure Your MCP Host

Path 1 — MCP Hosts (No LLM key required)

Path 2 — With Boyce's Built-in NL→SQL

Environment Variables

MCP Tools

Architecture

Scan CLI

Verify the Install

SemanticSnapshot Format

Project Layout

Status

Support