diff --git a/docs/cli.md b/docs/cli.md
index ad59fcd9..407337e3 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -6,6 +6,7 @@ The `haiku-rag` CLI provides complete document management functionality.
     Global options (must be specified before the command):
 
     - `--config` - Specify custom configuration file
+    - `--read-only` - Open database in read-only mode (blocks writes, skips upgrades)
     - `--version` / `-v` - Show version and exit
 
     Per-command options:
@@ -17,6 +18,7 @@ The `haiku-rag` CLI provides complete document management functionality.
     ```bash
     haiku-rag --config /path/to/config.yaml list
     haiku-rag --config /path/to/config.yaml list --db /path/to/custom.db
+    haiku-rag --read-only search "query"
     haiku-rag add -h
     ```
 
@@ -234,6 +236,9 @@ haiku-rag serve --monitor --mcp --agui
 
 # Custom MCP port
 haiku-rag serve --mcp --mcp-port 9000
+
+# Read-only mode (excludes write MCP tools, disables monitor)
+haiku-rag --read-only serve --mcp
 ```
 
 See [Server Mode](server.md) for details on available services.
diff --git a/docs/mcp.md b/docs/mcp.md
index 357ce383..7aa5bc10 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -63,8 +63,13 @@ haiku-rag serve --mcp --mcp-port 9000
 
 # stdio transport (for Claude Desktop)
 haiku-rag serve --mcp --stdio
+
+# Read-only mode (excludes write tools)
+haiku-rag --read-only serve --mcp --stdio
 ```
 
+**Read-only mode:** When `--read-only` is specified, write tools (`add_document_from_file`, `add_document_from_url`, `add_document_from_text`, `delete_document`) are not registered. Only search and query tools remain available.
+
 ## Claude Desktop Integration
 
 Add to your Claude Desktop configuration (`claude_desktop_config.json`):
diff --git a/docs/python.md b/docs/python.md
index f459ae1b..9b9dd31a 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -17,11 +17,19 @@ async with HaikuRAG("path/to/database.lancedb", create=True) as client:
 async with HaikuRAG("path/to/database.lancedb") as client:
     # Your code here
     pass
+
+# Open in read-only mode (blocks writes, skips upgrades)
+async with HaikuRAG("path/to/database.lancedb", read_only=True) as client:
+    results = await client.search("query")  # Read operations work
+    # await client.create_document(...)  # Would raise ReadOnlyError
 ```
 
 !!! note
     Databases must be explicitly created with `create=True` or via `haiku-rag init` before use. Operations on non-existent databases will raise `FileNotFoundError`.
 
+!!! note
+    Read-only mode is useful for safely accessing databases without risk of modification. It blocks all write operations, skips database upgrades on open, and prevents settings from being saved.
+
 ## Document Management
 
 ### Creating Documents