realy-mcp

# realy-mcp An MCP server that answers natural-language questions about **your** database by composing validated table operations, and returns typed rows plus a reviewable trace of every step. You run it. In your environment. Against your database. On your model credentials. Nothing is sent anywhere you did not configure — see [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md). --- ## Install ```bash pip install "realy-mcp[openai,postgres]" ``` Extras select what gets installed: providers (`openai`, `anthropic`, `google`, `groq`) and the optional DuckDB backend (`duckdb`). PostgreSQL/psycopg is included by default; `postgres` remains a compatibility extra. Pick only what you use — a customer on Azure OpenAI never has an Anthropic SDK on disk. Python 3.10–3.13. The install is a database driver and an SDK; there is no pandas, no numpy, no ML stack. ## Configure Create [`realy.toml`] and edit it. An example: ```toml [connection] id = "main" url_env = "REALY_DB_URL" # env var NAME, not the URL read_only = true [[connection.tables]] name = "claims" source_table = "v_claims_scoped" # a view you control description = "One row per submitted claim. `amount` is USD..." [model] provider = "openai" model = "gpt-4o" api_key_env = "REALY_MODEL_API_KEY" base_url = "https://my-azure.openai.azure.com/v1" # optional ``` Two things to get right: **Secrets are named, not written.** `url_env` and `api_key_env` hold the *names* of environment variables. The config file itself contains no credentials, so it can be committed and reviewed. **`description` is the highest-value field in the file.** It is what the calling agent reads to decide whether a question is answerable here, and what stops the agent guessing at a column's meaning. Write it as if explaining the table to a new analyst — including the traps ("`paid_amount` is NULL until settlement"). Set up these enviroment variables: ```bash export REALY_DB_URL='postgresql+psycopg://realy_ro:...@db.internal/warehou…