Connect with Claude Code or any coding agent
Hand your database connection to the coding agent open in your project, and give that agent RDST's local MCP tools.
Your project already knows how to reach its database. Instead of typing the connection details into RDST, you can paste a prompt into Claude Code, Cursor, Codex or any coding agent that's open in the project. The agent finds the connection string, adds the database to RDST, tests it and turns on monitoring, and RDST shows each step as it happens.
Everything in this flow stays on your computer. The agent talks to RDST at a local address, and RDST stores the password in your operating system's credential store.
Search for your databases
Add a database opens on Search for databases with Claude (or Codex), or Search this computer when no coding agent is installed. Nothing changes until you pick a database.
First RDST looks on this computer itself, in a few seconds, without an agent:
- Your recent projects: the folders your Claude Code and Codex sessions ran
in over the last 60 days. RDST reads the files there that can name a
database, whatever the language:
.envand Compose files, config, Terraform and other infrastructure files, and code that names a database host. It notes the database library a project depends on and the secret manager it uses, like Infisical, Doppler or 1Password, so a project whose database it can't place still shows up for your agent to finish. - Your agent and terminal history: the end of your recent Claude Code and Codex sessions and your shell history, for the databases you or your agent connected to.
- Docker containers: running PostgreSQL and MySQL containers and the ports they publish.
- Databases running on this computer: servers listening on a port. RDST tells PostgreSQL and MySQL apart by how each answers a connection, without logging in.
- Saved connections: DBeaver, DataGrip, TablePlus, pgAdmin, Beekeeper
Studio, MySQL Workbench, VS Code's SQLTools and Azure Data Studio, plus
~/.pgpass,pg_service.confand~/.my.cnf.
The list groups the databases by project, then the ones running elsewhere on this computer. Databases seen only in your history come last, folded, since they say least about what you work on now. On Windows each of these covers WSL too. Nothing leaves your computer, and passwords stay in their files: RDST reads one only when you connect that database.
On a Mac, a project in a folder macOS asks about, like Documents, Desktop or Downloads, shows by name. RDST looks inside when you choose Look in this project, so macOS asks you once, then.
Then RDST checks which of them answer, without logging in: it asks each server whether it speaks PostgreSQL or MySQL. Databases that aren't running, like a test container you stopped, and hosts that no longer exist are left out. One that exists but doesn't answer from this computer, like a database in a private network, stays in the list marked Not reachable from here: it may be fine, and Claude can help reach it. Rows also say when a database runs in WSL or Docker, and which provider hosts it. Databases RDST already has show first, under Already in RDST, with Open.
With an agent, it then picks the databases you work on, usually in under a minute, while RDST shows what it's checking. It reads only the project folders RDST found, and you get its short list, grouped by project, with a line on what each one is. See everything RDST found shows the whole list instead. Not what you're looking for? Tell the agent in the box under the list, and it answers in the same conversation with a new short list. Without an agent, the list is everything that answers, grouped by project.
Pick one database. Production ones are labeled and never picked for you. Details on a row shows what pointed RDST at it and where its password is. Then:
- Connect tries it right away when its URL or password is on disk, with no agent, and opens its Turn on monitoring screen when it connects. RDST saves a database only once it connects, whether you or your agent adds it. A Supabase URL on the transaction pooler moves to the session pooler on the same host, since monitoring needs it, and a Supabase project whose direct address this network can't reach (it's IPv6-only) is reached through its pooler: RDST looks the pooler up with the project's access token or your Supabase sign-in. If it doesn't connect, RDST keeps nothing and says why, right in the list: Have Claude Code fix it starts from that error, or sign in to its provider, or enter the details yourself.
- Set it up here with Claude Code (or Codex) has your coding agent set up
just that database, in the background on your own Claude or ChatGPT account.
After a search, it's the same conversation, which already knows the database;
otherwise the agent works in the project folder it was found in. RDST shows
its steps: starting the agent, adding the database, checking it can be
monitored and turning monitoring on. The agent works out anything missing,
like the password or the port Docker publishes, and a jump host for a database
only one can reach. On a development database it runs the statements RDST
asks for, like
CREATE EXTENSION pg_stat_statements. It asks you before it starts a stopped database, changes a server setting or restarts one, and it never changes a production database or moves one to another port. When it needs you to decide something, RDST shows its question with the likely answers as buttons, and your pick goes back to it. When it's time to turn monitoring on, RDST opens that database's Turn on monitoring screen for you to read and click. With only the Claude or Codex desktop app installed, Set it up in the Claude app opens a conversation there with the prompt typed in. - Connect manually opens the connection form filled in with what RDST found; you add the password.
- Sign in to Supabase, Neon, DigitalOcean or AWS: a database hosted there with no password on disk is imported through that provider's sign-in.
- A database RDST already has says so, and Open takes you to it.
The conversations are named in your agent's app, like RDST: find your database and RDST: set up shop, so you can find them later.
Under Or work in your own app, Start in the Claude app (or Codex) opens a new conversation with the prompt typed in, and Copy a prompt gives you the prompt for any agent you already have open.
After a setup, Continue in Claude (or Codex) opens the same
conversation in your desktop app. Without the desktop app, Continue in a
terminal opens a terminal window that resumes it, once: the conversation
carries on there. RDST adds itself to the
agent's MCP servers first, the way rdst claude add does, so the conversation
keeps RDST's tools. From then on the conversation carries on in the app: answer
the agent there, while RDST shows Continuing in Claude and keeps its steps
up to date as the agent adds the database and turns monitoring on. RDST starts a
new conversation when it needs the agent in the background. Otherwise RDST
remembers which conversation set up each database, and picks it up again when
that database needs the agent later. Once you've taken a conversation to the
Claude or Codex app, a database's fixes carry on there: Continue in the
Claude app opens it, with the error copied to paste.
Let your agent fix a failed check
When a database's Turn on monitoring screen says a check failed, like
pg_stat_statements not being created yet, choose Fix with Claude (or
Codex). The agent picks up the conversation that set the database up, when there was
one. It runs the statements RDST lists for that database, such as
CREATE EXTENSION pg_stat_statements, through RDST's own connection, so it never
needs the password. Before changing a server setting or restarting the
database, it asks you, and if you'd rather do it yourself it says exactly what
to change. The screen checks again when it's done. This works the
same for a database you imported from Supabase, Neon, DigitalOcean or AWS.
The same panel also offers Start in the Claude app (or Codex app) and Copy a prompt. They give your own agent a prompt written for this database and this step, so you can watch it work in your own conversation. If RDST can't run an agent for you, those two are what the panel shows.
Connect your agent to RDST
Once a database is monitored, its page has a Connect Claude or Codex to RDST card. It's a local connection between your agent and this app, so your agent can pull what RDST sees: the time series, Actions and index plans.
- Connect Claude or Connect Codex opens that app on the conversation that set the database up. If there wasn't one, it starts a new one with the prompt typed in. Without the app, it adds RDST to that agent's CLI instead.
- Copy a prompt works with any coding agent.
- After connecting, Or add RDST to every Claude Code conversation adds RDST to Claude Code's MCP servers, so you can ask about the database anywhere.
RDST doesn't change your database itself. Your agent changes it only when you ask it to, shows you the exact change first, and never touches a production database without your say-so.
Hand a database to your agent
- Open Add a database. Under Rather have your coding agent do it?, choose Start in the Claude app (or Codex app) to open a new conversation with the prompt typed in, or Copy a prompt.
- Send the prompt in the app, or select Copy prompt and paste it into your agent.
- Watch the checklist. It moves through Agent connected, Database added, Connection tested and Monitoring on as the agent works. When monitoring is on, the database's page opens.
If the agent hits a problem, the dialog shows the error RDST reported. Your agent can try again, or you can open the database and finish there, or add it by hand.
What the prompt asks the agent to do
The prompt explains that RDST is a local database monitoring app from Readyset and gives the address it's running at on this computer. It then asks the agent to:
- Talk to RDST's local MCP endpoint with curl. Nothing needs installing or registering.
- Work out which database the project uses, the way it would to run the app locally, then show you what it found and ask you to confirm. With more than one, it asks which; with none, it asks you.
- Add the database with
rdst_add_database. When the settings are in a file RDST can open, the agent passes the file's path and variable name so RDST reads them itself. - Run
rdst_check_prerequisites. If query stats aren't on, the agent shows you RDST's instructions and asks before running anything. - Call
rdst_enable_monitoring. The first time, RDST shows you its Turn on monitoring screen and you turn monitoring on yourself. Signed out, that's where you sign in to Readyset for free AI. - Tell you the name RDST saved the database under and whether monitoring is on.
The prompt asks the agent to keep connection details out of its replies. It
also tells the agent it can keep using RDST's tools afterwards to read what
RDST finds, and to call rdst_action with did_it after it applies a fix so
RDST updates right away.
The prompt carries no secret. It holds RDST's local address and nothing that expires, so a copied prompt keeps working.
The local MCP endpoint
While RDST is running, it serves MCP (Streamable HTTP) at /mcp on its local
address, for example http://127.0.0.1:51234/mcp. RDST keeps the same port
across restarts while it's free. Requests need no credentials: /mcp answers
only this computer, as the rest of RDST's local API does.
The tools act on the running app directly, so whatever an agent changes shows up in RDST right away.
| Tool | What it does |
|---|---|
rdst_status | Lists each database, whether its password is saved and whether it's monitored, plus whether you're signed in for AI |
rdst_add_database | Saves a PostgreSQL or MySQL database from a URL, a .env-style file and variable, or connection fields, with an SSH jump host when one is needed |
rdst_ask_user | During a setup RDST started: asks you to decide something about the database you picked, like which jump host reaches it, as a question with two to four choices RDST shows as buttons. Your pick comes back to the agent in the same conversation |
rdst_propose_databases | Adds the databases the agent found to the list in RDST's latest search, for you to pick from |
rdst_run_setup_statement | Runs one CREATE EXTENSION or GRANT statement that rdst_check_prerequisites lists for a database, over RDST's own connection |
rdst_wait_for_monitoring | Waits up to about 50 seconds for you to turn monitoring on, and returns as soon as you do |
rdst_test_database | Connects and reports whether RDST can read query statistics |
rdst_enable_monitoring / rdst_disable_monitoring | Turns monitoring on or off. Turning it off keeps the history |
rdst_get_monitor_settings / rdst_update_monitor_settings | Reads or changes analysis mode, caps and notifications |
rdst_list_inbox / rdst_get_inbox_item / rdst_inbox_action | Reads Inbox findings and marks them seen, snoozed, dismissed, resolved or reopened |
rdst_list_actions / rdst_get_index_plan | Reads the ranked plan of changes with their SQL, and a database's index plan |
rdst_action | Marks an action done (did_it, which RDST checks against the database), dismissed or undone, so the plan updates right away |
rdst_target_health | Reads a database's load, latency and connection readings |
rdst_top_queries / rdst_query_detail | Ranks queries by share of database time and shows one query's statistics and assessment |
rdst_latest_report | Reads the newest checkup report |
rdst_add_database reports persisted: false when the credential store isn't
available. RDST then keeps the password only until it restarts.
Register RDST with Claude Code
With the RDST CLI installed, run
rdst claude add while RDST
is running:
rdst claude addIt reads RDST's current address from desktop-server.json in the RDST data
directory and runs:
claude mcp add --transport http rdst http://127.0.0.1:<port>/mcpAn existing rdst entry is replaced. Start a new Claude Code session to use
the tools. If RDST's address changes, run rdst claude add again. You can
also copy the same command from Settings, under Use RDST from your
coding agent. When RDST isn't running,
rdst claude add registers the CLI's own MCP server over stdio instead.
Run it on the same system as RDST. Inside WSL, rdst claude add reads the
Linux side's data directory and can't see RDST running on Windows; use the
prompt there instead.
WSL
When RDST runs on Windows and your agent runs inside WSL, how the agent reaches RDST depends on WSL's networking mode.
- Mirrored networking (
networkingMode=mirroredin.wslconfig):127.0.0.1inside WSL reaches Windows, so the prompt's main address works as is. - The default NAT networking:
127.0.0.1inside WSL is the Linux VM, so the main address isn't reachable. When Windows has a vEthernet (WSL) network adapter as RDST starts, RDST also listens on the Windows side of that adapter. The prompt includes that address and tells the agent to use it if the main one doesn't answer.
The WSL listener serves only /mcp, and only to requests addressed to the
WSL adapter's address. RDST checks for the adapter while it runs, so starting
WSL after RDST works too.
If the agent still can't reach the WSL address, Windows Defender Firewall is probably blocking inbound connections on the WSL adapter. Allow RDST through the firewall for that network, or switch WSL to mirrored networking.
RDST on Windows opens a .env file inside WSL through the WSL share, so an
agent in WSL can pass the file's path as WSL names it.
Agents RDST runs on Windows
When RDST runs an agent itself (to set a database up or fix a
check), it uses the Windows Claude Code or Codex, so the conversation can
continue in the Windows desktop app or a Windows terminal. A WSL-only agent is
used when there's no Windows one. The agent is told how to reach WSL: it reads
files through \\wsl.localhost\<distro>\ paths and runs commands there, like
docker port, with wsl.exe. Windows Codex can't start wsl.exe inside its
sandbox, so when WSL is present RDST runs it without one; its instructions still
keep it to reading, or to the steps RDST asks for.
Security model
- Local only. The desktop app's main listener is on
127.0.0.1. The WSL listener serves only/mcp. None of these steps send anything to Readyset. - No web pages.
/mcprefuses requests from other machines, requests a browser page sends (they carry the page'sOrigin), and requests addressed to any host name other than127.0.0.1,localhost,[::1]or the WSL address, which stops DNS rebinding. - Passwords in the credential store. RDST stores database passwords in Keychain on macOS, Credential Manager on Windows and the Secret Service on Linux. No tool returns a password.
Your agent reads your project files with its own permissions, and what it reads may go to the agent's model provider under that agent's terms. The prompt asks it not to print or repeat credentials. See Privacy and data handling for what RDST itself stores and sends.