docs(skills): enforce Web UI as sole method for connection info setup (#1455)

Author: goldmedal

docs/getting_started_with_claude_code.md

@@ -33,7 +33,7 @@ This installs the following skills into `~/.claude/skills/`:
 | Skill | Purpose |
 |-------|---------|
 | `wren-quickstart` | End-to-end guided setup |
-| `wren-connection-info` | Configure database credentials |
+| `wren-connection-info` | Connection field reference per data source |
 | `generate-mdl` | Generate MDL from a live database |
 | `wren-project` | Save and build MDL as YAML files |
 | `wren-mcp-setup` | Start the Docker container and register MCP |
@@ -156,23 +156,43 @@ docker logs wren-mcp
 
 > **Database on localhost?** If your database runs on your host machine, replace `localhost` / `127.0.0.1` with `host.docker.internal` in your connection settings — the container cannot reach the host's `localhost` directly.
 
-### Phase 3 — Generate the MDL
+### Phase 3 — Configure connection and register MCP server
 
-In Claude Code, run:
+Configure connection info in the Web UI at `http://localhost:9001` — select the data source type and enter credentials. Use `/wren-connection-info` in Claude Code for field reference per data source.
+
+> **Connection info can only be configured through the Web UI.** Do not attempt to set it programmatically.
+
+Then register the MCP server with Claude Code:
+
+```bash
+claude mcp add --transport http wren http://localhost:9000/mcp
+```
+
+Verify it was added:
+
+```bash
+claude mcp list
+```
+
+**Start a new Claude Code session** — MCP servers are only loaded at session start.
+
+### Phase 4 — Generate the MDL
+
+In the new session, run:
 
 ```
 /generate-mdl
 ```
 
 The skill will:
 
-1. Run `health_check()` to verify the connection is configured
+1. Run `health_check()` to verify the connection is working
 2. Ask for your data source type (PostgreSQL, BigQuery, Snowflake, etc.) and optional schema filter
-3. Call `list_remote_tables()` and `list_remote_constraints()` via the MCP server to introspect your database schema
+3. Call `list_remote_tables()` and `list_remote_constraints()` via MCP tools to introspect your database schema
 4. Build the MDL JSON (models, columns, relationships)
 5. Validate the manifest with `deploy_manifest()` + `dry_run()`
 
-> **Connection info** must be configured in the Web UI (`http://localhost:9001`) before running `/generate-mdl`. Use `/wren-connection-info` in Claude Code for field reference per data source.
+> **Prerequisite:** The MCP server must be registered and a new session started (Phase 3). The `/generate-mdl` skill uses MCP tools — do not call ibis-server API directly.
 
 Then save the MDL as a versioned YAML project:
 
@@ -182,22 +202,6 @@ Then save the MDL as a versioned YAML project:
 
 This writes human-readable YAML files to your workspace and compiles `target/mdl.json`.
 
-### Phase 4 — Register the MCP server
-
-Add Wren to Claude Code's MCP configuration:
-
-```bash
-claude mcp add --transport http wren http://localhost:9000/mcp
-```
-
-Verify it was added:
-
-```bash
-claude mcp list
-```
-
-**Start a new Claude Code session** — MCP servers are only loaded at session start.
-
 ---
 
 ## Verify and start querying
@@ -250,9 +254,10 @@ docker restart wren-mcp            # restart
 | `health_check()` | Verify Wren Engine is reachable |
 | `query(sql=...)` | Execute SQL against the deployed MDL |
 | `deploy(mdl_file_path=...)` | Load a compiled `mdl.json` |
-| `setup_connection(...)` | Configure data source credentials |
 | `list_remote_tables(...)` | Introspect database schema |
 
+> **Note:** Connection info is configured exclusively through the Web UI at `http://localhost:9001` — there is no MCP tool for setting credentials.
+
 ---
 
 ## Troubleshooting
@@ -289,3 +294,20 @@ To update a single skill:
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force generate-mdl
 ```
+
+---
+
+## Locking down with read-only mode
+
+Once you have confirmed that queries are returning correct results and the MDL is working as expected, enable **read-only mode** in the Web UI:
+
+1. Open `http://localhost:9001`
+2. Toggle **Read-Only Mode** to on
+
+When read-only mode is enabled:
+
+- The AI agent can **query data** and **read metadata** through the deployed MDL as usual
+- The AI agent **cannot** modify connection info, change the data source, or call `list_remote_tables()` / `list_remote_constraints()` to introspect the database directly
+- This limits the agent to operating within the boundaries of the MDL you have defined, preventing it from accessing tables or schemas you have not explicitly modeled
+
+We recommend enabling read-only mode for day-to-day use. Turn it off temporarily when you need to regenerate the MDL or change connection settings.

docs/quickstart.md

@@ -141,9 +141,9 @@ docker ps --filter name=wren-mcp
 curl http://localhost:8000/health
 ```
 
-#### Phase 2 — Configure the connection and generate the MDL
+#### Phase 2 — Configure connection and register MCP server
 
-Before generating the MDL, configure the DuckDB connection via the Web UI at `http://localhost:9001`:
+Configure the DuckDB connection via the Web UI at `http://localhost:9001`:
 
 1. Open `http://localhost:9001` in your browser
 2. Select data source type: **DUCKDB**
@@ -161,33 +161,37 @@ The JSON looks like:
 
 > **Common mistake:** Do not point `url` to the `.duckdb` file directly (e.g. `/data/jaffle_shop.duckdb`). The ibis-server expects a **directory** — it scans for all `.duckdb` files in that directory and attaches them automatically. Pointing to the binary file causes a UTF-8 decode error.
 
-After saving the connection, run the skills in sequence in Claude Code:
+Then register the MCP server with Claude Code:
 
-```text
-/generate-mdl
+```bash
+claude mcp add --transport http wren http://localhost:9000/mcp
 ```
 
-Then save the MDL as a versioned YAML project:
+Verify it was added:
 
-```text
-/wren-project
+```bash
+claude mcp list
 ```
 
-This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`.
+**Start a new Claude Code session** — MCP servers are only loaded at session start.
 
-#### Phase 3 — Register the MCP server
+#### Phase 3 — Generate the MDL
 
-```bash
-claude mcp add --transport http wren http://localhost:9000/mcp
+In the new session, run the skills in sequence:
+
+```text
+/generate-mdl
 ```
 
-Verify it was added:
+The skill uses MCP tools (`health_check()`, `list_remote_tables()`, etc.) to introspect the database — these tools are only available after the MCP server is registered and a new session is started.
 
-```bash
-claude mcp list
+Then save the MDL as a versioned YAML project:
+
+```text
+/wren-project
 ```
 
-**Start a new Claude Code session** — MCP servers are only loaded at session start.
+This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`.
 
 </details>
 
@@ -273,7 +277,24 @@ Check container logs: `docker logs wren-mcp`. Confirm ports are listening: `curl
 |------|---------|
 | Add or edit MDL models | `/wren-project` |
 | Write custom SQL | `/wren-sql` |
-| Connect a different database | `/wren-connection-info` |
+| Connect a different database | Web UI at `http://localhost:9001` (use `/wren-connection-info` for field reference) |
 | Day-to-day usage guide | `/wren-usage` |
 
 For a deeper dive into how skills work or how to connect a cloud database, see [Getting Started with Claude Code](./getting_started_with_claude_code.md).
+
+---
+
+## Locking down with read-only mode
+
+Once you have confirmed that queries are returning correct results and the MDL is working as expected, enable **read-only mode** in the Web UI:
+
+1. Open `http://localhost:9001`
+2. Toggle **Read-Only Mode** to on
+
+When read-only mode is enabled:
+
+- The AI agent can **query data** and **read metadata** through the deployed MDL as usual
+- The AI agent **cannot** modify connection info, change the data source, or call `list_remote_tables()` / `list_remote_constraints()` to introspect the database directly
+- This limits the agent to operating within the boundaries of the MDL you have defined, preventing it from accessing tables or schemas you have not explicitly modeled
+
+We recommend enabling read-only mode for day-to-day use. Turn it off temporarily when you need to regenerate the MDL or change connection settings.

mcp-server/README.md

@@ -203,13 +203,15 @@ schema discovery. No local database drivers need to be installed on the MCP serv
 
 ### How it works
 
-The agent calls ibis-server tools in sequence:
+The agent calls MCP tools in sequence:
 
 ```
 User  → "Generate an MDL for my PostgreSQL ecommerce database"
 
-Agent → setup_connection(datasource="POSTGRES",
-          conn_info={"host":"localhost","port":"5432","user":"...","database":"shop"})
+User  → (configures connection info via Web UI at http://localhost:9001)
+
+Agent → health_check()
+      ← "Wren Engine is reachable."
 
 Agent → list_remote_tables()
       ← [{"name":"orders","columns":[...]}, {"name":"customers","columns":[...]}, ...]
@@ -227,6 +229,8 @@ Agent → deploy_manifest({"catalog":"wren","schema":"public","dataSource":"POST
       ← "MDL deployed successfully (5 models, 23 columns)"
 ```
 
+> **Note:** Connection info can only be configured through the Web UI — there is no MCP tool for setting credentials.
+
 ### Environment Variables
 
 | Variable | Required | Description |

skills/generate-mdl/SKILL.md

@@ -5,18 +5,18 @@ compatibility: Requires a running ibis-server (default port 8000). No local data
 license: Apache-2.0
 metadata:
   author: wren-engine
-  version: "1.3"
+  version: "1.4"
 ---
 
 # Generate Wren MDL
 
 ## Version check
 
 Silently fetch `https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json`.
-Compare the `generate-mdl` key with this skill's version (`1.3`).
+Compare the `generate-mdl` key with this skill's version (`1.4`).
 If the remote version is newer, notify the user before proceeding:
 
-> A newer version of the **generate-mdl** skill is available (remote: X.Y, installed: 1.3).
+> A newer version of the **generate-mdl** skill is available (remote: X.Y, installed: 1.4).
 > Update with:
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force generate-mdl
@@ -34,13 +34,15 @@ Follow these steps in order. Do not skip steps or ask unnecessary questions betw
 
 ### Step 1 — Verify connection and choose data source
 
+> **Connection info can ONLY be configured through the Web UI at `http://localhost:9001`.** Do not attempt to set connection info programmatically via ibis-server API calls, curl, or any other method. The ibis-server does not expose a public API for writing connection info — only the Web UI can do this.
+
 Confirm the MCP server has a working connection before proceeding:
 
 ```text
 health_check()
 ```
 
-If the health check fails, ask the user to configure the connection via the Web UI at `http://localhost:9001` before continuing.
+If the health check fails, or if the user has not yet configured a connection, direct them to the Web UI at `http://localhost:9001` to enter their data source credentials. Wait for the user to confirm the connection is saved before continuing.
 
 Ask the user for:
 1. **Data source type** (e.g. `POSTGRES`, `BIGQUERY`, `SNOWFLAKE`, …) — needed to set `dataSource` in the MDL
@@ -207,6 +209,6 @@ When in doubt, use `VARCHAR` as a safe fallback.
 
 ## Connection setup
 
-Connection info is configured via the MCP server Web UI at `http://localhost:9001`. See the **wren-mcp-setup** skill for Docker setup instructions.
+Connection info is configured **exclusively** via the MCP server Web UI at `http://localhost:9001`. There is no API endpoint for setting connection info — do not attempt to configure it programmatically. See the **wren-mcp-setup** skill for Docker setup instructions.
 
 > **Note:** If the Web UI is disabled (`WEB_UI_ENABLED=false`), connection info must be pre-configured in `~/.wren/connection_info.json` before starting the container. Use `/wren-connection-info` in Claude Code for the required fields per data source.

skills/index.json

@@ -7,7 +7,7 @@
   "skills": [
     {
       "name": "wren-connection-info",
-      "version": "1.3",
+      "version": "1.4",
       "description": "Reference guide for Wren Engine connection info — required fields, sensitive values, Docker host hints, and BigQuery credential encoding.",
       "tags": [
         "wren",
@@ -20,7 +20,7 @@
     },
     {
       "name": "generate-mdl",
-      "version": "1.3",
+      "version": "1.4",
       "description": "Generate a Wren MDL manifest from a live database using MCP server introspection tools.",
       "tags": [
         "wren",
@@ -82,7 +82,7 @@
     },
     {
       "name": "wren-quickstart",
-      "version": "1.2",
+      "version": "1.3",
       "description": "End-to-end quickstart for Wren Engine — from zero to querying.",
       "tags": [
         "wren",
@@ -100,7 +100,7 @@
     },
     {
       "name": "wren-usage",
-      "version": "1.0",
+      "version": "1.1",
       "description": "Daily usage guide for Wren Engine — connect, query, manage MDL, and operate the MCP server via AI agents.",
       "tags": [
         "wren",

skills/versions.json

@@ -1,9 +1,9 @@
 {
-  "generate-mdl": "1.3",
-  "wren-connection-info": "1.3",
+  "generate-mdl": "1.4",
+  "wren-connection-info": "1.4",
   "wren-project": "1.5",
   "wren-sql": "1.0",
   "wren-mcp-setup": "1.3",
-  "wren-quickstart": "1.2",
-  "wren-usage": "1.0"
+  "wren-quickstart": "1.3",
+  "wren-usage": "1.1"
 }

skills/wren-connection-info/SKILL.md

@@ -4,14 +4,14 @@ description: Reference guide for Wren Engine connection info — explains requir
 license: Apache-2.0
 metadata:
   author: wren-engine
-  version: "1.3"
+  version: "1.4"
 ---
 
 # Wren Connection Info Reference
 
 This skill answers questions about how to configure connection info for each data source in Wren Engine. Use it to explain required fields, flag sensitive values, and guide the user through any data-source-specific setup steps.
 
-The connection info is entered by the user — in the MCP server Web UI (`http://localhost:9001`) for normal use, or directly in API calls for advanced workflows.
+Connection info can **only** be configured through the MCP server Web UI at `http://localhost:9001`. There is no ibis-server API for writing connection info — do not attempt to set it programmatically via API calls, curl, or any other method. Always direct the user to the Web UI to enter or update credentials.
 
 ---