BDI Copilot

A conversational copilot for Boomi Data Integration (BDI), delivered as a Claude Code plugin. Build, operate, troubleshoot, and optimize your BDI pipelines by talking — no UI loops, no ID hunting, no log spelunking.

v1.10.0 · build-pipeline slim-down (~5–10s happy path) + enum-tags hotfix · 2026

Naming note: this README uses "BDI Copilot" as the customer-facing name. The plugin's internal identifier in code is boomi-bdi-copilot (and the slash commands are /rivery-*) — you'll see both throughout, that's expected.

---

Table of contents

1. What is BDI Copilot?
2. Who it's for
3. What it does — the four verbs
4. The fourteen skills
5. The six specialist sub-agents
6. Safety guarantees
7. Requirements
8. Install
9. First-run setup (the six-prompt wizard)
10. Connecting the BDI docs MCP (kapa)
11. Daily use
12. Switching environments
13. Troubleshooting
14. Privacy & where your data lives
15. Support & feedback

---

What is BDI Copilot?

BDI Copilot turns the questions you already ask BDI every day — "What ran last night?", "Why did this fail?", "How do I ship this to prod?", "Where is my RPU spend going?" — into a single sentence in chat.

It runs inside Claude Code and connects to your BDI account through your personal API token. It reads your environments, rivers, runs, connections, and logs in real time, and — only with your explicit confirmation — applies changes through BDI's public API.

It is read-heavy by design. Every diagnosis, every recommendation, every status report is read-only. Writes (create, edit, run, disable, copy a river) are deliberate: each one is presented as a Confirm — <ACTION> block that waits for your yes before the call goes through. Every successful write is appended to a local audit log you can read back at any time.

When the answer depends on BDI's own documentation — error codes, CDC behavior, loading-mode semantics, connector specifics — the copilot consults the official BDI docs through the kapa MCP server and cites the source URL verbatim. No training-data guessing on diagnoses.

---

Who it's for

Three personas live inside this plugin:

	Persona	Driver	Daily questions
DE	Data engineer on call	pager-driven · operate	"What ran last night?" · "Why did this fail?" · "Can I rerun it from here?"
AE	Analytics engineer shipping new flows	project-driven · build	"Sync these tables to Snowflake." · "Promote it to staging." · "Is incremental safe here?"
DO	Data ops lead watching the bill	cost-driven · optimize	"Which rivers cost the most?" · "What's failing 100% of the time?" · "What can I safely cut?"

If any of those is your job — or you toggle between all three — BDI Copilot is built for you.

---

What it does — the four verbs

Every capability rolls up into one of four verbs:

1. Operate — what ran

See last night's runs, today's failures, what's in flight right now — grouped, scoped to your active env, no scrolling. Rerun a single river, activate a disabled one, or pause a runaway — every write behind a confirm. → /rivery-operate

2. Troubleshoot — why it broke

Pick a failing river. The copilot finds the most recent failed run, pulls the CSV log, parses it, dispatches the incident-responder sub-agent, cites the relevant BDI doc, names the root cause, and drafts the fix. You see the verdict, you say apply the fix, the copilot writes a Confirm — EDIT block, you say yes, and the patch ships. → /rivery-troubleshoot

3. Build — ship the next one

From "sync Postgres to Snowflake" to a created, scheduled, first-run-completed river. The copilot consults pipeline-architect for river type, extraction mode, loading mode, schedule, and schema-drift posture; uses sql-writer if you need a Logic-River SQL body; pre-flights the pipeline live (connection liveness, schema/table existence, target db/schema existence) via validate_pipeline in ~30s before any write; verifies the persisted river after create to catch silent field-drops; presents every write as a confirm; routes OAuth-based sources to the BDI UI for the OAuth dance; and watches the first run. → /rivery-build

4. Optimize — stop the bleed

Ranked recommendations: dead rivers, over-frequent schedules, full-loads that should be incremental — each line carries an estimated RPU saved per month, a risk level, and a rationale citing specific runs. You pick which one to apply, the copilot walks the change behind a confirm. One at a time. Never bulk-apply. → /rivery-optimize-cost

A fifth verb — Discover — sits before Build: list connections in this env, drill into source tables and schemas, pick what to ingest before designing anything (/rivery-discover). Health sits before Optimize: a last-N-days digest of success rate, top failures, top RPU consumers, with a smart hand-off to optimize-cost when an RPU spike is detected (/rivery-health). And Versioning supports Troubleshoot and Optimize: list every edit to a river with author + timestamp, view any prior config, diff two versions in plain English with a HIGH/MEDIUM/LOW risk tag, and — under a typed-phrase confirmation — restore the river to an earlier version (/rivery-versions). When the diagnosis of a failed run shows the river was edited in the 24h before the failure, troubleshoot-failure automatically appends a one-line summary of what changed and a one-click rollback link.

---

The fourteen skills

Four setup & orientation skills, two discover/build-data skills, two Logic-river skills, two operate/troubleshoot skills, and four optimize/govern skills.

#	Skill	Trigger	What it does
1	onboarding	/rivery-onboarding	First-run setup — region, token, active env, stated goal, kapa MCP install. Six prompts, ~2 minutes.
2	help	/rivery-help	Capabilities tour + intent router. Routes transactional asks to the right journey; consults kapa for conceptual asks.
3	switch-environment	/switch-environment	Pick a different env to operate on. Fuzzy-matches names ("Stagng" → "Staging"), updates state.json atomically.
4	operate-pipelines	/rivery-operate	Daily ops: what ran, what failed, what's running. Group by status. Rerun, activate, disable behind confirm.
5	troubleshoot-failure	/rivery-troubleshoot	End-to-end diagnosis with log evidence, doc citations, and a proposed patch you can apply or refuse. Surfaces a recent-edit advisory when the river was changed within 24h before the failure.
6	analyze-pipeline-health	/rivery-health	Env-wide overview — success rate, RPU spend, hot incidents — with smart hand-offs to optimize or troubleshoot.
7	discover-data	/rivery-discover	Browse what's actually behind a connection — tables, columns, sync-mode hints — before you build anything.
8	build-pipeline	/rivery-build	From intent to first run, with a designed config, live pre-flight validation (connection liveness + schema/table/db checks before any write), OAuth-aware UI handoffs, post-create persistence verification, and a bounded first-run watch.
9	promote-changes	/rivery-promote	Diff two envs, copy a river across, remap connections by title — never auto-resolves an ambiguous match.
10	optimize-cost	/rivery-optimize-cost	Ranked savings — dead rivers, over-frequent schedules, full-to-incremental swaps — applied one at a time.
11	manage-versions	/rivery-versions	List a river's edit history, view a prior config, diff two versions in plain English with risk tag, or restore — gated by a typed-phrase confirmation, never yes.
12	rivery-capabilities	/rivery-capabilities	Print the plugin's current capability surface — covered endpoints (87% of 171), 219 supported source/target connectors, 25 pre-flight foot-guns, known platform gotchas, catalog version. Read-only.
13	rivery-build-logic	/rivery-build-logic	Build a new Logic river (multi-step ETL / orchestration) end-to-end — natural-language, template (master_scheduler, daily_rollup, multi_step_etl), or step-by-step. Footgun pre-flight before every write.
14	rivery-edit-logic	/rivery-edit-logic	Modify an existing Logic river — add/edit/reorder steps, change connections, activate, run — each write behind confirmation.

Every skill leads its reply with a status banner so you always know which environment you're operating in before you read a single number.

---

What's new in v1.10.0 — the build-pipeline slim-down

build-pipeline was rewritten from 10 steps to 6. A unified TTL cache (tools/rivery_cache.py, 20-min default, mutation-driven invalidation) front connections / rivers / connection-types; a wizard composer replaces the pipeline-architect sub-agent on the happy path (still available via --explain); the 4-probe pre-flight is reused from discovery (full pre-flight via --strict); and three write-confirm prompts collapse into one combined create + run prompt. Result: happy-path wall-clock ~5–10s (was ~80–100s) on warm cache. A follow-on enum-tags hotfix (2026-05-28) lowercases discriminator tags and adds a pre-flight WriteRiverInput gate at the composer tail. See CHANGELOG.md for the full entry.

---

What's new in v1.9.7 → v1.9.9 — the build-pipeline reliability release

Three releases tighten the create-river path so a build that passes the copilot's checks actually runs end-to-end against api.rivery.io.

v1.9.9 — parallel validation (3.4× speedup)

validate_pipeline() now runs its 4 expensive pull-requests concurrently via ThreadPoolExecutor(max_workers=4). Happy-path wall-clock on mysql → snowflake dropped from ~116s (v1.9.8 sequential) to 33.8s measured against the live API — a 3.4× speedup with identical report shape and bug-catching.

Knob	Value
validate_pipeline(parallel: bool = True, ...)	default-on; set False for deterministic ordering in tests
_INFLIGHT_PULL_REQUESTS = threading.Semaphore(4)	process-wide cap, stays under api-service's 6/min rate limit
Four _probe_* helpers	each catches its own exceptions, returns _ProbeResult, never raises

v1.9.8 — pre-flight validation + post-create verification

New module tools/pipeline_validation.py with two public functions:

Function	When it runs	What it catches
validate_pipeline(...)	before compose_river_body / create_river	dead connections, wrong target db (the RIVERY_DEFAULT_DB case), typo'd schema/table — in ~30s instead of waiting for RVR-ACTIVATE-500 at activation time
verify_river_persisted(...)	after create_river returns	silent api-service field-drops (e.g. is_selected=False despite sending True); discriminator rewrite; unexpected river_status

The 9 pre-flight checks:

1. source_connection_exists — GET /connections/{id}
2. source_connection_alive — pull-request get_schemas:<source> succeeded with results
3. source_schema_exists — named schema in #2's result
4. source_table_exists — pull-request get_db_metadata:<source> (DB) or get_metadata:<source> (SaaS)
5. target_connection_exists — GET /connections/{id}
6. target_connection_alive — pull-request get_databases:snowflake / get_datasets:bigquery / get_buckets:s3 / …
7. target_database_exists — named db in #6's result, with did-you-mean suggestions on miss
8. target_schema_exists — pull-request get_schemas:<target> with database_name
9. body_shape — local Pydantic validation against WriteRiverInput

Liveness classifier maps every failed pull-request to one of 5 categories (credentials_dead, not_reachable, legacy_connector, target_missing, unknown) with a clear remediation string. Failures route to UI handoff or surface did-you-mean suggestions — never opaque tracebacks.

v1.9.7 — source-gate audit + per-source live validation

Evidence-based audit against the api-service source: identified 16 strict-bar API-creatable sources (membership in SourceTypeEnum ∧ not in private_values() ∧ has a *AdditionalSourceSettings Pydantic class). Two were previously over-gated:

Source	Before v1.9.7	After
Salesforce	oauth_ui_handoff	native — POST /rivers works once the OAuth connection exists
TikTok	cms_ui_only	native — has TiktokAdditionalSourceSettingsInput in api-service

Also fixed: compose_river_body now fills required target fields (database_name, schema_name, dataset_id, bucket_name) per the api-service target validators, closing the 422 on POST.

Drift-detection meta-tests (tests/test_gate_drift.py) catch the day api-service grows or shrinks the candidate set.

Why these three matter together

Without them	With them
6 of 16 strict-bar sources blocked at the gate	All 16 reachable via the native path
8/16 live POSTs failed 422 on target validators	16/16 round-trip cleanly
Bad target db / dead connection → activation fails 30+ seconds in with RVR-ACTIVATE-500	Caught in <30s pre-flight with did-you-mean suggestions and Console deep-link
Silent is_selected field drops detected only by manual UI inspection	verify_river_persisted catches it on every create
validate_pipeline cost: ~116s (would feel like a hang in build-pipeline)	~34s parallel — fast enough to run inline before every create

---

What's new in v1.9.0 — the catalog-aware release

v1.9.0 vendors a runtime catalog of the entire Rivery REST API surface into the plugin. Skills and sub-agents consult it before drafting any recommendation; payload validation catches malformed bodies before the API does; every footgun rule, every connector, every endpoint is queryable in O(1) at runtime.

What changed under the hood (the 7-phase enhancement):

Phase	Tag	What it does
α	alpha-runtime-catalog-loader	Vendored catalog at tools/_catalog/ (7 JSON + 32 Tier-0 docs); tools/rivery_catalog.py exposes a frozen-dataclass catalog singleton with O(1) lookups for 171 endpoints, 596 schemas, 219 connectors, 25 rules, 6 gotchas.
β	beta-payload-validation	tools/payload_validation.py — lightweight pre-flight schema validator. Opt-in validate=True on create_river + create_connection. Catches the "missing required field" 422 before the API call.
γ	gamma-generic-endpoint-dispatcher	RiveryAPI.call_endpoint(endpoint_id, ...) — single generic dispatcher reaches all 171 catalog endpoints without per-endpoint methods.
δ	delta-connector-aware-river-creation	tools/river_body_builder.py:compose_river_body(...) + RiveryAPI.create_river_with_connectors(...) ergonomics — pass source/target api_names + connection IDs, body is composed and validated.
ε	epsilon-skills-agents-catalog-aware	tools/catalog_retrieval.py with 7 helpers; 6 sub-agents (pipeline-architect, incident-responder, transformation-expert, logic-builder, cost-optimizer, sql-writer) consult the catalog before drafting. 3 skills (build-pipeline, discover-data, troubleshoot-failure) have catalog-aware pre-flight steps.
ζ	zeta-footgun-rules-from-catalog	15 → 25 footgun rules, the new 10 derived from the catalog (recipe_source_missing_recipe_id, unsupported_source_type_via_api, connector_capability_mismatch_cdc, etc.).
η	eta-rivery-capabilities	/rivery-capabilities skill + catalog-driven coverage floor test (87% covered, 50% floor).

Test + perf coverage (test-perf-plan-v1): 888 tests collected, 824 passing, 40 sub-system scenarios with perf: budgets across 4 dimensions (HTTP queries, latency, tokens, memory). Hermetic by default, opt-in pytest -m live tier.

Refreshing the catalog as BDI ships new connectors: the snapshot under tools/_catalog/ is regenerated by Boomi's internal catalog-generation tooling and committed into the plugin. It ships pre-built — there's nothing for you to refresh.

---

The six specialist sub-agents

Each is a focused, read-only sub-agent. They consult — they don't write. The skill that calls them surfaces their verdict to you, and you always confirm before anything changes.

Sub-agent	Used by	What it does
incident-responder	troubleshoot-failure	Walks the failure backwards from the CSV log to a clear root-cause verdict — every claim cites a log line, a config field, or a prior run timestamp.
cost-optimizer	optimize-cost · health	Reads recent activity and returns the top 5 savings opportunities sorted by RPU/month, with a stated risk level on each.
pipeline-architect (Opus)	build-pipeline · promote	Picks river type, extraction mode, loading mode, schedule, schema-drift posture — with rationale grounded in BDI's own docs.
transformation-expert	build · promote · optimize	SCD-1 vs SCD-2, dedup, late-arriving rows, idempotency — recommends the loading pattern that matches your business semantics.
sql-writer	build-pipeline · troubleshoot	Snowflake, BigQuery, Postgres, Redshift — drafts Logic-River SQL with intent comments and ambiguity flags. Never executes.
logic-builder	rivery-build-logic · build-pipeline	Translates a natural-language prompt into a Logic-river logic_steps[] tree (logic_shape, template_hint, step tree). Drafts only — never executes.

pipeline-architect runs on Claude Opus because pipeline design is where expert reasoning matters most. The other five run on Claude Sonnet.

---

Safety guarantees

The plugin is built around four principles. They're enforced both in the skills' instructions and in shell-level PreToolUse hooks.

1 · Context — status banner first

Every reply leads with which environment is active. You always know where you are before you read a single number.

env · BDI (US)   region · us   token · valid   last action · operate-pipelines

2 · Consent — confirm every write

Every mutation — create, edit, run, disable, copy — pauses for your yes. Reply cancel, dry-run, or anything ambiguous, and the call doesn't happen.

⊥ Confirm — EDIT   target: orders-sync   env: Production
                    patch:  schedule cron   reply: yes · cancel · dry-run

3 · Trace — audit every change

Each successful write appends one line to ~/.claude/rivery/state.json:mutation_audit — verb, target, env, status, timestamp. You can read it back any time.

✓ EDIT-RIVER   orders-sync   env=Production   status=success   ts=2026-05-03T16:04:11Z

4 · Restore — typed-phrase confirmation

Restoring a river to a previous version overwrites the entire current config. For this one operation only, the regular yes/cancel confirm isn't enough — the copilot prints a literal phrase encoding the river name and both version shorts, and you must paste it back exactly. Bare yes / proceed / confirm all cancel.

To proceed, paste this exactly:
   I understand this overwrites orders-sync from a1b2c3d4 to e5f6g7h8

Anything else — including 'yes' or 'proceed' — cancels.

Plus, by construction:

• Titles in chat. IDs only in tool calls. You think in "Production", not in 61b9....
• Tokens are never typed in chat. The copilot reads your BDI API token from a local .env file (mode 600), not from an interactive prompt — so it can't be echoed, logged, or accidentally pasted into a transcript.
• OAuth sources hand off to the UI. Salesforce, HubSpot, Google Sheets, and the rest of the OAuth-based connectors can't be created from the API — the copilot opens a deep-link to the right BDI UI page and waits.
• CDC bookmark resets always go through the UI. Per BDI's CDC point-in-time docs, bookmark resets aren't safe over the API. The copilot diagnoses, proposes, and hands off.
• Cancel-run isn't on BDI's public API — the copilot tells you so and hands off to the UI rather than pretending.
• 25-rule pre-flight footgun layer. Every write is checked against a catalog of known BDI platform pitfalls (CDC ordering, schema-drift posture, full-load-on-large-table, etc.) before the confirm is shown — high-severity rules block, lower ones warn inline.

---

Requirements

• Claude Code — install from https://claude.com/claude-code.
• A BDI account with a personal API token. Generate one in the BDI UI: My Profile → API Tokens → New Token. The token must have access to at least one environment.
• Python 3.10+ on your machine. Used by the plugin's tool wrappers.
• Strongly recommended: the BDI docs MCP server (kapa). The diagnostic and design skills are materially better when grounded in official docs.

You do not need:

• A BDI admin account (a regular user token is enough, if it has env access).
• A separate BDI account for each environment — one token typically covers Production / Staging / Sandbox in the same account.
• An OpenAI / Anthropic key beyond what Claude Code already uses.

---

Install

Clone the public repository anywhere on your machine — your home directory or ~/plugins/ is fine.

git clone https://github.com/RiveryIO/bdi-plugin.git ~/plugins/bdi-plugin
# you should now have ~/plugins/bdi-plugin/

Then load it into Claude Code. Two paths — pick one:

Path A — Run from the directory (try it)

Best for first-time evaluation. The plugin is active only for sessions launched from this directory.

cd ~/plugins/bdi-plugin
claude

Claude Code picks up the plugin's skills, agents, and hooks from the current working directory automatically.

Path B — Install as a marketplace plugin (pin it)

Best for keeping the plugin available across all Claude Code sessions and surviving restarts. Add it straight from GitHub — this works in Claude Code and in Cursor (via the Claude Code extension); the mechanism is identical:

claude plugin marketplace add RiveryIO/bdi-plugin
claude plugin install boomi-bdi-copilot@rivery

(You can also point the marketplace at a local clone instead of GitHub: claude plugin marketplace add ~/plugins/bdi-plugin.)

The plugin now loads in every Claude Code session. claude plugin uninstall boomi-bdi-copilot removes everything it added. To pull updates later, re-run claude plugin marketplace update rivery.

Using natively in Cursor (no Claude Code extension)

If you use Cursor's own Agent, install the BDI Copilot as native Cursor Skills:

git clone https://github.com/RiveryIO/bdi-plugin.git ~/plugins/bdi-plugin
bash ~/plugins/bdi-plugin/install/cursor-setup.sh

This registers the 14 skills (type / in Cursor Agent to invoke), a bdi CLI launcher, the rivery-docs docs MCP, and credential/environment guard hooks — globally, so they work across all your projects. Set your token in ~/.claude/rivery/.env (see First-run setup). Re-run after git pull to update; install/cursor-setup.sh --uninstall removes it. Full details in install/cursor-setup.md.

(Alternatively, the Claude Code extension in Cursor runs this plugin via Path B above — same mechanism as Claude Code.)

After any path, the next thing you'll do is set up your token (see below) and run /rivery-onboarding (/onboarding in Cursor).

---

First-run setup (the six-prompt wizard)

Setup has two parts: (a) write your BDI API token to a local .env file once (a single shell step, ~30 seconds), then (b) run the /rivery-onboarding wizard in Claude Code (six prompts, ~2 minutes).

(a) Save your BDI API token to ~/.claude/rivery/.env

Generate a token in the BDI UI: My Profile → API Tokens → New Token. Then write it to a local file the copilot will read on every call. Never paste the token into the Claude Code chat — pasting secrets in chat risks them ending up in conversation transcripts, screen-shares, and copy-paste buffers. The .env file stays on your machine, with file mode 600 (owner read/write only).

# create the directory and write the token in one shot
mkdir -p ~/.claude/rivery
umask 077                                  # ensures the new file is 600
cat > ~/.claude/rivery/.env <<'EOF'
DATA_INTEGRATION_API_TOKEN=<paste-your-token-here>
EOF
chmod 600 ~/.claude/rivery/.env            # belt-and-braces

Verify the file's permissions:

ls -l ~/.claude/rivery/.env
# expected: -rw-------  1 you  staff  ...  ~/.claude/rivery/.env

That's the only step that ever touches the secret. From now on, the wizard and every skill read it from disk — the token never appears in chat.

If you'd rather use an environment variable instead of a file, you can export DATA_INTEGRATION_API_TOKEN=... in your shell profile and skip the .env file. The wrappers read both. The .env is the recommended default because it persists across shell sessions without polluting your shell rc.

(b) Run /rivery-onboarding in Claude Code

The wizard walks a six-prompt checklist. Total time: ~2 minutes.

1 · Pick your region

Welcome to BDI Copilot. Which region is your BDI account in — US or EU?

The region picks the API endpoint. US → https://api.rivery.io. EU → https://eu-api.rivery.io. Wrong region is the most common cause of a "token rejected" failure — a token issued in the EU won't authenticate against the US API, and vice versa.

2 · Confirm your token is on disk

I see a token at ~/.claude/rivery/.env. I'll never read it back to you, never log it, and never echo it in chat. Ready to validate?

The copilot does not ask you to paste the token. It picks up the file you wrote in step (a) and runs two silent checks:

• A local JWT decode that reads the acc (account ID) and env claims out of the token. No network. If the string isn't a valid JWT, the copilot apologizes and asks you to fix ~/.claude/rivery/.env.
• A live validation call against GET /v1/accounts/<acc>/environments. If the API returns 401/403, the copilot offers to switch regions or asks you to rotate the token in the BDI UI. No partial state is saved on failure.

If the file is missing entirely, the copilot prints the snippet from step (a) and asks you to run it in your shell, then come back and say ready.

3 · Pick the active environment

You have access to these environments:

• Production
• Staging
• Sandbox

Which one should I treat as your active environment for now?

The copilot resolves your pick by title (no IDs in chat). It handles fuzzy matches and ambiguous matches gracefully — if you type "stage" and there's a "Staging" and a "Stage-2", it asks you to disambiguate.

From this point on, every reply leads with the status banner so you always know which env is active.

4 · Tell us what brings you here

Last quick question: what brings you here today? A few words is plenty — for example "I need to get our Salesforce → Snowflake pipeline running again", or "I'm building a new Postgres ingestion", or "just exploring".

The copilot saves your answer verbatim and uses it to recommend the three most-relevant skills on the welcome screen and in /rivery-help. Saying "operate" gets you operate-pipelines, troubleshoot-failure, and analyze-pipeline-health up top. Saying "build" leads with discover-data, build-pipeline, promote-changes.

5 · Connect the BDI docs MCP

Almost-required: install the BDI documentation MCP server. The plugin's diagnostic skills consult BDI's own docs through this MCP — testing showed quality is dramatically higher with it than without.

This is technically optional, but the copilot leads with strongly recommended language for a reason: the diagnostic and design skills (troubleshoot-failure, build-pipeline, optimize-cost, promote-changes, analyze-pipeline-health) explicitly halt and ask you to connect kapa before they'll proceed.

See Connecting the BDI docs MCP (kapa) below for the two commands.

6 · Done — welcome screen

You see the active env, a one-line snapshot of what's been moving data in it recently (top connector types, count of active rivers in last 7 days), and three suggested next-step skills based on what you wrote in step 4.

The copilot persists everything to ~/.claude/rivery/state.json in one atomic write. From now on, you can type /rivery-help any time to see the full menu, or jump straight to a skill by name.

---

Connecting the BDI docs MCP (kapa)

Boomi hosts an MCP server backed by the full BDI documentation corpus. Wiring it up gives every diagnostic and design skill live retrieval over the official BDI docs, and lets the copilot cite source URLs verbatim ("per BDI's CDC troubleshooting docs at help.boomi.com/.../mysql-cdc-troubleshooting, CALL mysql.rds_set_configuration('binlog retention hours', 168) for RDS").

Two-step install

Step 1 — register the server. Run this in Claude Code (the leading ! runs it as a shell command in your session):

! claude mcp add --scope user --transport http rivery-docs https://rivery.mcp.kapa.ai/

This only registers the server. It does not authenticate.

Step 2 — OAuth authenticate. Type /mcp in Claude Code to open the MCP-server panel, find rivery-docs in the list, and click Authenticate. A browser tab opens; complete the OAuth flow there, close the tab, and you'll see "Authentication successful. Connected to rivery." back in chat.

Verifying it's working

Type /rivery-help what does RPU mean? — if kapa is connected, the answer cites a BDI doc URL. If not, the copilot tells you plainly that kapa isn't usable and shows the connection block again.

What works without it

All fourteen skills run without kapa, but they degrade:

• troubleshoot-failure, build-pipeline, rivery-build-logic, optimize-cost, promote-changes, and analyze-pipeline-health will halt at any diagnostic / design / advisory step and ask you to connect kapa before they continue. This is intentional — training-data-only answers were materially less trustworthy on BDI specifics.
• operate-pipelines, discover-data, rivery-edit-logic, switch-environment, manage-versions, rivery-capabilities, and onboarding work fully without kapa — they're operational, not advisory.
• help falls back to local reference files for conceptual questions and tells you it's doing so.

Re-authenticating mid-session

OAuth tokens can expire mid-session. If a kapa call returns "requires re-authorization", type /mcp and click Authenticate on rivery-docs again — no re-registration needed.

---

Daily use

Every interaction follows the same shape: type a slash command (or just ask in natural language), the copilot leads with the status banner, runs the skill, presents you with the answer or the proposed change, and waits for your input.

Some example sessions

"What ran last night?"

/rivery-operate

env · BDI (US) · last action · — 

Yesterday's runs · 24h window
─────────────────────────────────
 ✓ orders-sync         success · 02:12 · 14 RPU
 ✓ users-mirror        success · 02:30 · 8 RPU
 ✗ events-stream       failed  · 03:51 · 0 RPU (CDC)
 ⏵ inventory-snapshot  running · started 04:02

"Why did events-stream fail?"

/rivery-troubleshoot events-stream

Resolving river…       match: events-stream
Most recent failed run · 2026-05-04T03:51:02Z
Pulling logs…          47 rows · top error: "GTID has been purged from binary log"
Consulting BDI docs (kapa MCP)…

Diagnosis · MySQL CDC binlog purged
 • Root cause — MySQL purged binary logs BDI still needed to replay.
 • Evidence  — log row #4: "GTID set 21d…:1-9842 has been purged"
 • BDI says (help.boomi.com/.../mysql-cdc-troubleshooting):
     › CALL mysql.rds_set_configuration('binlog retention hours', 168) for RDS
     › expire_logs_days = 7-10 for self-managed MySQL
 • Proposed fix — bookmark reset is UI-only (per BDI's CDC docs).
                  I'll hand off when you say go.

Reply "apply the fix" to walk the change, or "no thanks".

"What changed on orders-sync recently?"

/rivery-versions orders-sync

env · BDI (US) · last action · — 

History of `orders-sync` · 4 versions
──────────────────────────────────────────────
 #  id        when              by              🔖
 -  --------  ----------------  --------------  -
 1  a1b2c3d4  2026-05-07 14:22  Alice Sterling     (current)
 2  e5f6g7h8  2026-05-06 09:11  Bob Liu         🔖
 3  c9d0e1f2  2026-05-04 16:48  Alice Sterling
 4  3a4b5c6d  2026-04-28 10:00  Carol Mendez

Use `diff @a1b2c3d4 @e5f6g7h8` to compare, `restore @e5f6g7h8` to roll back.

Talking in natural language

You don't have to type slash commands. The copilot's help skill routes any of these to the right journey:

• "Did orders-sync run last night?" → operate-pipelines
• "Why did users-mirror fail this morning?" → troubleshoot-failure
• "Build a Postgres → Snowflake sync for the public.orders table." → build-pipeline
• "What's expensive this month?" → optimize-cost
• "Promote orders-sync from staging to production." → promote-changes
• "Show me a weekly digest." → analyze-pipeline-health
• "What sources do we have connected?" → discover-data
• "Who edited orders-sync and what did they change?" → manage-versions
• "Roll back orders-sync to yesterday." → manage-versions

---

Switching environments

Type /switch-environment (no argument needed). The copilot lists the envs your token can see, you pick by title, and the active env updates atomically. You can also pass the name directly:

/switch-environment Staging

Fuzzy-matching is built in — "prod", "production", "prdoction" all resolve to "Production". Ambiguous matches (two envs both starting with "Stage") prompt you to disambiguate; the copilot never picks for you.

---

Troubleshooting

"Token rejected" during onboarding

Most likely cause: wrong region. Re-run /rivery-onboarding and pick the other region. If that's not it, the token may have been rotated in the UI — generate a new one in My Profile → API Tokens, overwrite ~/.claude/rivery/.env with the new value (same DATA_INTEGRATION_API_TOKEN=... shape), and re-run the wizard.

"No environments are visible"

Your token authenticated, but no environments are scoped to it. Ask a BDI admin to grant your token access in the UI: Settings → API Tokens → (your token) → Environments. Re-run /rivery-onboarding after that.

Diagnostic skill halts asking for kapa

The kapa MCP server is either not registered, or its OAuth has expired. Type /mcp, find rivery-docs, click Authenticate. If it's not in the list at all, run the registration command from the kapa section first.

Logs aren't available for a failed run

BDI only retains CSV logs for some river types. The copilot detects this and renders a UI handoff with a deep link to the run page. Diagnosis falls back to whatever the activity-stream metadata exposes plus your run history.

Plugin needs to be re-installed

claude plugin uninstall boomi-bdi-copilot
claude plugin install boomi-bdi-copilot@rivery

Your ~/.claude/rivery/state.json and .env survive the reinstall. Run /rivery-onboarding only if you want to re-do the wizard from scratch.

Python wrapper errors ("ModuleNotFoundError" etc.)

The plugin's tool wrappers run on Python 3.10+. Check with python3 --version. The wrappers use only the standard library plus requests — if you see an import error, pip install requests resolves it.

---

Privacy & where your data lives

• Your BDI API token lives in ~/.claude/rivery/.env with file mode 600 (owner read/write only). Never typed in chat. Never echoed back. Never sent to Anthropic.
• Your local state — region, active env, env cache, river name cache, connection name cache, mutation audit log — lives in ~/.claude/rivery/state.json (mode 600).
• API calls to BDI go directly from your machine to api.rivery.io (US) or eu-api.rivery.io (EU) — through your token, with TLS, never proxied through Anthropic or Boomi infrastructure.
• Calls to the kapa MCP server go to rivery.mcp.kapa.ai and return documentation snippets only. They don't carry your BDI token or your data.
• Conversations with the copilot are processed by Claude Code per its standard data-handling policy.

You can audit every change the copilot has made: cat ~/.claude/rivery/state.json | jq .mutation_audit.

---

Support & feedback

• BDI account, billing, connector issues: your existing Boomi support channel is the right place — the copilot is a layer on top, not a replacement.
• Copilot questions, bug reports, feature requests: reach out to your Boomi point of contact and reference "BDI Copilot v1.10.0". We'd love to hear what's working and what's missing on your real environments.

Stop clicking. Start asking.