# Agents

Bobby Tables runs a Model Context Protocol server inside the app, so a coding agent in your codebase can read the real schema, run read-only queries and ask you to run changes. Every change is approved by you in the app.

## Where to find it

| Action | How |
| --- | --- |
| Turn it on | `Preferences…`, `⌘,` (`Ctrl+,`), then `Agents` and `Allow agents to connect` |
| Connect a client | `Connect a client` in the same pane, then `Copy` |
| See what agents did | `Recent activity` in the pane, and the `Agents` indicator in the status bar |
| Change what a connection allows | The `Connection access` table in the pane, for database and file connections alike |
Agent access is off until you turn it on, and then listens on a socket file only your own account can open.

## Connecting a client

Every client runs the same thing: the app binary with one argument, `mcp`, registered as `bobby-tables`. Copy the line from `Connect a client`, which fills in your own path; agents launch Bobby Tables themselves if it is not already open.

Claude Code takes it as one command.

```
claude mcp add bobby-tables -- "/Applications/Bobby Tables.app/Contents/MacOS/bobby-tables-app" mcp
```

Codex reads it from `~/.codex/config.toml`.

```
[mcp_servers.bobby-tables]
command = "/Applications/Bobby Tables.app/Contents/MacOS/bobby-tables-app"
args = ["mcp"]
```

Cursor reads it from `~/.cursor/mcp.json` or a project `.cursor/mcp.json`, and any other stdio client reads the same shape.

```
{
  "mcpServers": {
    "bobby-tables": {
      "command": "/Applications/Bobby Tables.app/Contents/MacOS/bobby-tables-app",
      "args": [
        "mcp"
      ]
    }
  }
}
```

## What agents can do

An agent reaches your connections through these tools, and nothing else.

### Read
| Tool | What it does |
| --- | --- |
| `list_connections` | Lists saved connections with host, database and environment tag. Never a password, token or key. |
| `list_databases` | Lists the databases on a connection's server. |
| `get_schema` | Describes a database's tables, views, functions and enum types. |
| `get_table` | Describes one table: columns, keys, indexes, constraints, triggers and DDL. |
| `query` | Runs a read-only statement and returns 200 rows, or up to 2,000 on request. |
| `get_result_rows` | Pages a result an earlier `query` stored, without re-running it. |
| `query_history` | Lists statements you have run, 100 at most. |
| `saved_queries` | Lists your saved queries with folder, name and SQL. |
### Propose
| Tool | What it does |
| --- | --- |
| `propose_write` | Asks you to run a change, with a sentence saying why. |
### Show in app
| Tool | What it does |
| --- | --- |
| `open_in_app` | Opens a query or a table in a workspace, so a large result stays in the grid. |
### Files
| Tool | What it does |
| --- | --- |
| `fs_list` | Lists one directory of an S3 or SFTP connection, a page per call. |
| `fs_stat` | Returns one entry's kind, size, modification time and type. |
| `fs_read` | Reads 256 KB of a remote file, or up to 1 MB on request. |
| `fs_download` | Asks you to download entries into a local folder. |
| `fs_upload` | Asks you to upload local entries into a remote directory. |
| `fs_delete` | Asks you to delete entries, counted first. |
| `fs_rename` | Asks you to rename one entry. |
| `fs_mkdir` | Asks you to create one directory. |

## Reads

The first time an agent touches a connection, the app asks, naming the client, the connection, its environment tag and the database. Answer `Allow for this app run`, `Always allow reads on this connection` or `Deny`; closing it is a refusal. The same question is asked before an agent lists or reads files on an S3 or SFTP connection, and the same answers apply.

Reads run on a separate session the driver opens read-only, so an agent never borrows a workspace you have open. Everything an agent runs appears in your own `History`.

## Approving changes

`propose_write` puts the statement on screen exactly as the agent wrote it, its reasoning quoted under `Why`. Nothing has run yet: `Approve` runs it, `Reject` sends back the reason you type, and `Open in editor` hands it to a SQL tab to finish yourself. A statement that creates or drops is labelled `Approve DDL` and needs a second click, and nothing pre-approves a write.

File changes use the same dialog with the paths in place of the statement, counting what a recursive delete would remove and what names an upload would meet. `Allow downloads to this folder for this app run` covers a folder rather than each file. Setting `Writes` to `Deny` on a file connection refuses uploads, deletes, renames and new folders before anything is shown; downloads are approved folder by folder regardless.

## Good to know

- The SQL tools work on PostgreSQL, CockroachDB, MySQL, MariaDB, TiDB, Microsoft SQL Server, ClickHouse, Snowflake, Oracle Database, SQLite and Cloudflare D1; the file tools work on S3 and SFTP.
- Redis, Valkey, Apache Cassandra, ScyllaDB, MongoDB, Google Cloud Firestore, Cloudflare Workers KV and Google BigQuery have no agent tools yet, and `list_connections` marks them `none`.
- A connection needs its password in the keychain; an agent can neither supply a credential nor change one.
- Open an SSH-tunnelled connection in the app once so its host key is trusted. An agent is never offered that prompt.
- An agent session counts against the same connection limits as a workspace.
- Agent access is not available on Windows yet.
- Nothing about agents leaves this computer. `Recent activity` is held in memory, never written to disk, and gone when the app quits.

## Related

- [Connections](https://bobbytables.app/docs/connections.md)
- [Engines, file sources and platforms](https://bobbytables.app/docs/engines.md)