Read-only MCP server
Give Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, or Claude Desktop direct read-only access to your configured SQL and NoSQL databases — zero passwords in config files, zero write paths, and production profiles physically hidden.
Enable read-only MCP access in three steps #
dataomni mcp runs inside the exact same binary as the desktop GUI, speaking JSON-RPC over stdio without opening a window. Sharing the binary identity means your AI agent uses your existing SSH tunnels, TLS certificates, and OS keychain secrets without ever seeing a password.
-
Save the database password to your OS keychain
Open the connection in DataOmni and keep "Save password to system credential store" checked. Because dataomni mcp runs as a separate child process, session-only passwords entered in memory are unreachable.
-
Opt the non-production profile into Read-only agent access
Verify the profile environment is Development, Test, or Staging, set "Command line & agent access" to Read-only, and click Save. DataOmni signs an HMAC-SHA256 capability (<id>#agent) into your OS keychain bound to the connection secret and endpoint.
-
Register dataomni mcp in your AI client
Pick your AI coding assistant below to copy its exact registration command or mcpServers JSON block.
claude mcp add dataomni -- /Applications/DataOmni.app/Contents/MacOS/dataomni mcp
| Platform | Executable path | Arguments |
|---|---|---|
| macOS | /Applications/DataOmni.app/Contents/MacOS/dataomni | mcp |
| Linux (.deb / .rpm) | /usr/bin/dataomni | mcp |
| Windows (NSIS / MSI) | %LOCALAPPDATA%\DataOmni\dataomni.exe or C:\Program Files\DataOmni\dataomni.exe | mcp |
How production stays invisible and writes stay blocked #
Production profiles are physically invisible, not merely refused
Connections marked Production force agent access off in the UI, omit any keychain grant, do not appear in tools/call connections, and return not_found if queried by name.
- Tamper-evident keychain grant: editing connections.json on disk to flip environment from production to development or enable agent access fails HMAC-SHA256 verification against the secret in your OS keychain.
- Live revocation without server restart: dataomni mcp re-reads connections.json and verifies the keychain grant on every tool call. Turning off agent access in the GUI hides the connection on the very next call.
- Two-barrier read-only execution: every SQL call accepts only a single read statement (SELECT, WITH without nested writes, SHOW, DESCRIBE, EXPLAIN without ANALYZE, VALUES, TABLE) AND executes inside a database read-only transaction (BEGIN READ ONLY / START TRANSACTION READ ONLY / SET TRANSACTION READ ONLY / readonly=1 / read-only file handle with DuckDB external access locked off) ending in ROLLBACK.
- No host filesystem side-channels: export, backup, and csv-preview are intentionally excluded from MCP so non-shell agents cannot write or read arbitrary local files through DataOmni.
- Statement-free audit trail: every call logs timestamp, connection name, tool, first SQL keyword, byte length, SHA-256 digest, outcome, row count, and duration to dataomni-cli.log — never logging literal query text.
Pair with a read-only database user for defense in depth
Read-only transactions cannot block non-mutating server administration functions granted to superusers (such as PostgreSQL pg_terminate_backend or MySQL get_lock()). Always connect agents with a least-privilege read-only database account.
All 11 read-only MCP tools #
Every tool carries readOnlyHint: true in tools/list and returns structured JSON with "schema": 1 (dictionary returns whole-database Markdown ready for LLM context). Unknown extra arguments or option-like positional values starting with -- are rejected as usage errors.
| Tool | Arguments | What it returns |
|---|---|---|
| connections | (none) | Lists non-production connections explicitly opened to agents (never leaks passwords or key paths). |
| dictionary | connection | Whole-database Markdown data dictionary (tables, columns, types, PKs, FKs) — call this first before writing SQL. |
| schema | connection, table? | Lists tables and views, or columns, indexes, and foreign keys for a specific table. |
| ddl | connection, table | Returns the database engine's own canonical object definition (SHOW CREATE TABLE, DBMS_METADATA, sqlite_master). |
| query | connection, sql, limit?, timeout_seconds? | Executes one read-only SQL statement (default 200 rows, max 10,000, reports truncated: true when capped). |
| explain | connection, sql | Returns the estimated execution plan without running ANALYZE or mutating state. |
| test | connection | Checks connectivity; on failure attaches DNS and TCP port diagnosis. |
| mongo | connection, action, ... | Read-only MongoDB operations: collections, find, count, aggregate ($out / $merge refused), explain, structure. |
| redis | connection, action, ... | Read-only Redis operations: keyspaces, scan, get, and command (verified via server COMMAND INFO readonly flag). |
| neo4j | connection, action, ... | Read-only Cypher: labels and run (verified as read query via EXPLAIN plus Bolt read-mode routing). |
| es | connection, action, ... | Read-only Elasticsearch / OpenSearch: indices and segment-checked GET/HEAD or search POST (_search, _count, _msearch). |
Common MCP setup issues #
| Symptom | Cause & fix |
|---|---|
| connections returns [] or query says connection not found | Either the profile is marked Production, "Command line & agent access" is still Off, or connections.json was edited manually without saving in the GUI. Open Edit Connection in DataOmni, set Read-only, and click Save. |
| First tool call hangs on macOS | macOS Keychain is waiting behind your editor window for authorization. Switch to the system prompt, enter your macOS login password, and click "Always Allow" — dataomni mcp keeps waiting rather than dropping the stdio session. |
| SQL Server profile cannot enable agent access | SQL Server lacks a session-level READ ONLY transaction guarantee; agent access is intentionally disabled for SQL Server in the current version. |