Integration Guides

Connect Boyce to your MCP host in minutes.

MCP hosts — Claude Code, Cursor, VS Code, Codex, DataGrip/JetBrains, Claude Desktop — do not need a Boyce API key. The host’s own model handles reasoning. Boyce supplies schema context and deterministic SQL.

Step 1 — Install

pip install boyce

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

Then run the setup wizard — it auto-detects your MCP host and writes the config:

boyce init

Supports: Claude Code, Cursor, VS Code, Codex, DataGrip/JetBrains, Claude Desktop, Windsurf, and more. Or configure manually below.

Step 2 — Configure Your Host

Config file: .mcp.json in your project root (or ~/.claude/settings.json under mcpServers for global)

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}
  1. Run boyce init in your project root — it writes .mcp.json automatically
  2. Start a new Claude Code session in the project directory
  3. Test: “Call the boyce ingest_source tool on my schema, then get_schema.”

Claude Code discovers .mcp.json automatically when you start a session in a directory that contains one.

Config file: .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global)

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}
  1. Create .cursor/mcp.json in your project (or run boyce init)
  2. Reload Cursor: Cmd+Shift+P → Developer: Reload Window
  3. Open Cursor chat (Cmd+L) and test: “Use boyce get_schema to list available entities.”

VS Code supports MCP natively via .vscode/mcp.json (per-project) or user settings (global).

Config file: .vscode/mcp.json in your project root

{
  "servers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}
  1. Create .vscode/mcp.json in your project (or run boyce init)
  2. Reload VS Code: Cmd+Shift+P → Developer: Reload Window
  3. Open Copilot Chat and test: “Use boyce get_schema to list available entities.”

Requires VS Code 1.99+ with the Copilot Chat extension. MCP tools appear as agent tools in Copilot Chat.

OpenAI Codex CLI reads MCP server config from ~/.codex/config.toml.

Config file: ~/.codex/config.toml

[mcp_servers.boyce]
command = "boyce"
args = []

[mcp_servers.boyce.env]
BOYCE_DB_URL = "postgresql://user:pass@host:5432/dbname"
  1. Edit ~/.codex/config.toml (create the file and directory if they don’t exist)
  2. Start a new Codex session
  3. Test: “Use boyce get_schema to list available entities.”

BOYCE_DB_URL is optional. Without it, SQL generation works; EXPLAIN pre-flight returns "unchecked".

JetBrains IDEs (DataGrip, IntelliJ, PyCharm, WebStorm, etc.) support MCP via the AI Assistant plugin.

Settings path: Settings → Tools → AI Assistant → MCP Servers

  1. Open Settings (Cmd+,) → Tools → AI Assistant → MCP Servers
  2. Click + to add a new server
  3. Set command to boyce
  4. Optionally add environment variable BOYCE_DB_URL for live database features
  5. Click OK and restart the AI Assistant
  6. Test in AI chat: “Use boyce get_schema to list available entities.”

Requires JetBrains AI Assistant plugin with MCP support (2025.1+). Or run boyce init to auto-configure.

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

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

BOYCE_DB_URL is optional. Without it, SQL generation works; EXPLAIN pre-flight returns "unchecked".

  1. Edit the config file (create if it doesn’t exist)
  2. Restart Claude Desktop
  3. Look for the tools icon (hammer) in the chat input — Boyce tools should appear
  4. Test: “Call ingest_source on my schema file, then get_schema to show me what’s available.”

Step 3 — Load Your Schema

Point Boyce at your database or project. It figures out the rest:

# Scan a directory (auto-detects dbt, LookML, DDL, SQLite, Django, SQLAlchemy, Prisma, CSV, Parquet)
boyce scan ./my-project/

# Or ingest from your MCP host:
# Tool: ingest_source
# Args: source_path: "./my-project/"

Then verify with get_schema — it returns the full entity and field list your host LLM can reason about.

With a Live Database

Set BOYCE_DB_URL to unlock EXPLAIN pre-flight validation and column profiling:

export BOYCE_DB_URL="postgresql://user:pass@host:5432/mydb"
boyce   # MCP server on stdio with live DB adapter

Or add it to your MCP host config under "env" as shown in the tabs above.

Requires: pip install "boyce[postgres]" (adds asyncpg). All database access is read-only — write operations are rejected at two independent layers.

Other MCP Hosts

boyce init also supports Windsurf, Cline, and Continue.dev. Run it and follow the prompts:

boyce init

Any MCP host that supports stdio transport works with Boyce. Set the command to boyce and optionally add BOYCE_DB_URL as an environment variable.

CLI and HTTP API (Path 2)

For the CLI (boyce ask "...") and HTTP API (boyce serve --http), Boyce uses its internal query planner and requires an LLM key:

export BOYCE_PROVIDER=anthropic
export BOYCE_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=sk-ant-...
export BOYCE_DB_URL=postgresql://user:pass@host:5432/db

boyce ask "total revenue by customer segment last quarter"

Uses LiteLLM — supports Anthropic, OpenAI, Ollama (local), vLLM (local), Azure, Bedrock, Vertex, Mistral, and 100+ providers. Local LLM setup guide →

Troubleshooting

If Boyce tools don’t appear in your host, or you get connection errors: