safeselect

Why SafeSelect?

Give your coding agent the database context it needs to investigate a bug, understand a schema or inspect a query plan. SafeSelect exposes read-only tools for PostgreSQL and MongoDB, with local policy and bounded results.

• Debug with database context. Discover tables, collections and indexes before reading the rows or documents relevant to your task.

• Start with connections you already have. Import from DBeaver, Docker Compose or MongoDB Compass, including SSH-backed connections.

• Keep control of access. Set project-specific access rules, row limits and timeouts. Passwords stay in macOS Keychain or environment variables.

• Run locally. The agent connects over MCP stdio, with no MCP network listener. SafeSelect enforces its read-only tool surface even when the configured database credentials allow writes.

Related MCP server: db-mcp

See it in action

From Homebrew to a connected agent: import a DBeaver connection, keep its password in Keychain, and let OpenCode inspect an order through read-only tools. See the demo gallery for more clients, MongoDB and Linux onboarding.

Quick Start

Run setup from your repository root. You need a PostgreSQL or MongoDB connection and a Java 17+ runtime for database commands.

1. Install

On macOS with Homebrew:

brew install antonillos/tap/safeselect

For Linux, prebuilt binaries, asdf, Java setup or source builds, follow the installation guide.

2. Import a connection

Choose the source you already use:

Use your actual export or Compass directory, then follow the importer's driver and password setup steps. Keep secrets out of project files and chat. For a complete SSH-backed example, follow the DBeaver → Codex walkthrough.

3. Connect your agent

# Verify connectivity; this can open SSH tunnels and contact databases.
safeselect check

# Replace codex with opencode, or choose another supported client below.
safeselect agent install codex
safeselect agent status

If you have multiple environments, add --environment <name> to both check and agent install to select the intended database. Without it, check tests all environments; installation only infers a target when there is exactly one.

Open or restart your agent and approve the MCP server if prompted. Installation uses user scope by default; add --local for project scope where supported. See client setup and scopes.

4. Try it

Ask your agent:

Use SafeSelect to identify the connected backend. For PostgreSQL, list tables and describe one using catalog metadata. For MongoDB, list databases and collections only. Stop before reading rows or sampling documents.

Success: the agent reports the database identity and available tables or collections without needing a database password in the conversation. Then ask it to investigate a specific issue with a small, targeted read. MongoDB schema inference samples documents, so include that step only when you are ready to read data.

Need help? Run safeselect doctor --environment <name> and follow its next step. Diagnostics can contact the database. See the connection diagnostics or agent recovery guide.

Supported agents

OpenAI Codex · OpenCode · Claude Code · Cursor · Windsurf · GitHub Copilot · Gemini CLI

SafeSelect works with MCP clients over stdio. Built-in installation handles the clients above; the integration guide covers configuration, scopes and manual setup. Codex and OpenCode also receive four portable workflow skills. After updating SafeSelect, run safeselect agent upgrade <client> and reload your client.

Security and quality evidence

SafeSelect validates requests against project policy before database execution. Ordinary policy rejections return an error; serious security attempts and internal validation or audit failures stop the server. Result limits and timeouts bound reads, and query text is hashed for audit records.

The database security suites run against disposable PostgreSQL and MongoDB fixtures. Rejection cases check the expected error and compare the resulting database state with a baseline, so a rejected response alone is not enough to pass.

See how to verify a CI execution for results tied to a specific commit. Test source describes the checks; a successful matching run provides execution evidence. Pending or skipped suites are unverified, and badges can refer to a different revision.

Read the threat model and limits, the security model, or the architecture for the scope of these controls. For alternatives and tradeoffs, see the database MCP comparison.

Documentation

Feedback and contributions

Have a setup problem or a feature request? Open an issue. For setup feedback, include your client, OS and the step that failed; leave out credentials, connection exports and database contents. Report security vulnerabilities through the security policy.

Contributions are welcome—see Contributing to get started.

License

MIT.