Skip to content

mcp-server.md

Latest commit

 

History

History
152 lines (119 loc) · 6.88 KB

mcp-server.md

File metadata and controls

152 lines (119 loc) · 6.88 KB
Raw

MCP server

Querya Desktop can act as an MCP server. Any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Continue, ...) and whatever model it runs can then read the schema of the connections you share and run read-only SQL through Querya. Querya has no chat of its own and needs no AI provider keys: the client brings the model.

Supported: PostgreSQL, MySQL, SQLite (SQL tools) and MongoDB (document tools). Redis and extension drivers are not exposed yet.

How it works

MCP client ──stdio──▶ querya-mcp ──127.0.0.1 + token──▶ Querya Desktop (running)
                                                         └─ connections, SSH tunnels, keyring
  • The server runs inside the running app, so it uses your saved connections, SSH tunnels and passwords from the OS keyring. The model only sees each connection's id, name, type, environment tag and database name.
  • The client starts querya-mcp, a small bridge that forwards the MCP session to the app over a loopback socket. If Querya is not running (or the server is off), every request gets the error "Querya Desktop is not running or its MCP server is off".

Enable it

  1. Preferences → MCP Server → Enable MCP server. The status line shows the port and the number of connected clients.
  2. Under Shared connections, switch on the connections the model may read. Nothing is shared by default. Connections tagged Production show a PROD badge: the model can read everything the connection's database user can.
  3. Under Connect a client, press Copy … config for your client and paste it where the client keeps MCP servers (see below).

querya-mcp

Build Where it is
Linux zip / AppImage / .deb / .rpm next to the app binary, e.g. /opt/querya-desktop/querya-mcp
Windows zip / setup next to querya_desktop.exe in the install folder
macOS, Flatpak not bundled yet: download querya-mcp-v<version>-<platform> from the GitHub release

The copy buttons insert the bundled path automatically; otherwise replace /path/to/querya-mcp with where you put the downloaded binary.

Client configuration

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and most stdio clients:

{
  "mcpServers": {
    "querya": { "command": "/opt/querya-desktop/querya-mcp" }
  }
}

VS Code (.vscode/mcp.json or user settings):

{
  "servers": {
    "querya": { "type": "stdio", "command": "/opt/querya-desktop/querya-mcp" }
  }
}

Claude Code: claude mcp add querya -- /opt/querya-desktop/querya-mcp

Gemini CLI (~/.gemini/settings.json): the same mcpServers block as above.

Tools

Tool Arguments Returns
list_connections — shared connections: id, name, type, environment, database
list_tables connection_id tables and views with their column count
describe_table connection_id, table columns, types, primary key, foreign key targets, indexes
sample_rows connection_id, table, rows (1-100, default 20) first rows of the table
run_query connection_id, sql columns, rows, row_count, truncated
explain_query connection_id, sql (without EXPLAIN) the execution plan, without running the query

MongoDB connections use their own tools:

Tool Arguments Returns
list_collections connection_id collection names (system collections hidden)
find_documents connection_id, collection, filter, sort, limit (1-100, default 20) documents, count, truncated
count_documents connection_id, collection, filter count

filter and sort are JSON objects in MongoDB query syntax. Server-side JavaScript ($where, $function, $accumulator) is refused at any depth, as are documents nested more than 12 levels or with more than 500 fields. No tool writes: the connection's saved user may be able to, Querya never asks it to. Each call uses its own connection and closes it. The collection must exist, and string values longer than 4 KB are cut with a marker.

Resource: schema://<connection_id> — all tables with columns and keys, for clients that load context up front.

SQL errors come back as tool errors with the database's message, so the model can fix its query and retry.

Limits

  • Read-only. One statement per call; only SELECT, WITH without data-modifying parts, EXPLAIN (without ANALYZE), SHOW, DESCRIBE, VALUES, and schema PRAGMAs on SQLite. See security.md.
  • Rows: at most 1000 per run_query (truncated: true when cut), 100 per sample_rows. Cells longer than 4 KB are cut with a marker.
  • Time: 15 s per statement.
  • Tables: base tables and views of the current schema / database (kind: "view"; PostgreSQL materialized views included). A view has no primary key or index information.

Activity log

Preferences → MCP Server → Recent calls lists the last calls (time, client, tool, connection, SQL, rows and duration, or the error). The app keeps the last 200 in its local database; Clear empties it.

Troubleshooting

Symptom Fix
"Querya Desktop is not running or its MCP server is off" Start Querya and switch on Enable MCP server.
list_connections is empty Share at least one PostgreSQL / MySQL / SQLite / MongoDB connection.
"Connection N is not available" The connection was unshared or deleted; call list_connections again.
"Invalid Querya MCP token" The token was regenerated or the app restarted with a new one: restart the MCP client.
Client cannot find querya-mcp Use the absolute path; on macOS / Flatpak download the release binary and chmod +x it.
Several Querya instances Set QUERYA_MCP_ENDPOINT to a different file for each instance and for its querya-mcp.

The endpoint file (port and token) is $XDG_RUNTIME_DIR/querya/mcp-endpoint.json on Linux (fallback ~/.cache/querya), ~/Library/Caches/Querya/ on macOS and %LOCALAPPDATA%\Querya\ on Windows.

For contributors

  • MongoDB: lib/core/mcp/mcp_mongo_service.dart (service, guard, session).
  • Query core: lib/core/mcp/mcp_query_service.dart, guard mcp_sql_guard.dart, error redaction mcp_redaction.dart, read-only delegates mcp_sql_delegates.dart.
  • Server and transport: querya_mcp_server.dart (dart_mcp), mcp_socket_host.dart, mcp_server_controller.dart.
  • Bridge: packages/querya_mcp_bridge — a dependency-free package so dart compile exe produces one static binary (the app package has build hooks that dart compile exe refuses).
  • Settings UI: lib/features/settings/preferences_mcp_section.dart.
  • Tests: test/core/mcp/ (security suite: mcp_security_test.dart).
  • Epic: #1133.