Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.querybear.com/llms.txt

Use this file to discover all available pages before exploring further.

Codex is OpenAI’s terminal-based AI coding agent. It supports MCP via TOML configuration in ~/.codex/config.toml. QueryBear plugs in as an http MCP server.

​
Connect

Edit ~/.codex/config.toml (create it if it doesn’t exist) and add: 
[mcp_servers.querybear]
type = "http"
url = "https://mcp.querybear.com/mcp"
Restart the Codex CLI. The next tool call will trigger an OAuth handshake — Codex opens a browser, you approve, and it’s linked to your QueryBear account.

​
Verify

In a Codex session, ask:
“What QueryBear tools do you have?”
You should see list_connections, get_schema, and run_query.

​
Why QueryBear + Codex

Like other terminal agents, Codex is at its best when it can see the systems you’re working on. Databases are the highest-leverage thing to expose — and the most dangerous to expose naively. QueryBear gives Codex safe read access:
  • Generate SQL backed by real schemas, not hallucinated columns.
  • Answer “is this row what I think it is?” without leaving the terminal.
  • Cross-reference data between tables when debugging.
  • Build one-off analytics queries during a refactor.
All with the security guarantees of QueryBear’s gateway — read-only, allow-listed, audit-logged.

​
Per-database setup guides

PostgreSQL + Codex

Step-by-step Postgres setup, including read-only role SQL.

MySQL + Codex

Step-by-step MySQL setup, including read-only user SQL.

SQLite + Codex

Local SQLite file setup.

​
Tips for using QueryBear in Codex

  • TOML formatting matters. A misplaced = will silently disable the MCP server. If querybear doesn’t appear in Codex’s tool list, re-check the TOML block — common mistakes: missing type = "http", mistyped URL, indentation in places TOML doesn’t allow.
  • Be explicit about which connection. Codex tends to ask for list_connections repeatedly if you don’t name your target — “using the prod connection, count…” skips the round-trip.
  • The audit log lives in QueryBear. If a Codex session ran a query you don’t recognize, you can confirm in the QueryBear dashboard.

​
Common workflows

  • “Pull the schema for the events table and write a query that counts unique sessions per day for the last 30 days.”
  • “What’s the row count in users, subscriptions, and payments? I’m sizing a backfill.”
  • “Verify that no row in orders has status = 'pending' older than 24 hours.”