DataOmni icon DataOmni v1.1.0
中文 GitHub

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.

  1. 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.

  2. 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.

  3. Register dataomni mcp in your AI client

    Pick your AI coding assistant below to copy its exact registration command or mcpServers JSON block.

dataomni mcp & dataomni cli PROD HIDDEN
Standard stdio MCP — pick your AI tool and copy:
claude mcp add dataomni -- /Applications/DataOmni.app/Contents/MacOS/dataomni mcp
Binary path for dataomni mcp on each platform
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.

MCP tools exposed by dataomni mcp
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 #

Diagnosing MCP errors
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.