MCP and external databases
How the DMS MCP tools map an external Postgres, MySQL/MariaDB or MongoDB database into menu sections, and when they may write to it.
An AntelopeJS DMS project can connect to a database it does not own, such as a client's Postgres, MySQL/MariaDB or MongoDB database. The MCP server tools read its shape, map its tables into pages, and write to it only with the access the project grants. They never answer a value from its rows. See Connected database values.
Map tables into menu sections
builder_map_resources writes one TableView page per relation. A page goes in the connection's category, pages.<connection>, unless the resource names another one. To group pages into a section, first create the category with builder_create_category in the same module the tables are mapped into, then pass its ref on each resource. With section: true, the category is a section of its own in the sidebar, whose ref is its name, such as sales:
{
"module": "shop-tables",
"connection": "shop",
"resources": [
{
"relation": "public.orders",
"category": "sales",
"tableView": true,
"writable": false,
"fields": [{ "column": "reference" }, { "column": "total" }]
}
]
}
| Case | Result |
|---|---|
A category that is not a category, or that another module declares | The relation is refused, and none of its files are written. |
| A relation mapped again | Its page is updated where it is, even after a move with builder_configure_page. The builder finds the page by the table it holds. |
A remap with a new category | The page moves there, and its route changes. The answer holds a route_changed warning. Nothing redirects the old route. |
A remap without title, icon, description or order | The page keeps the values it has. A title you send sets both the page title and the table caption. |
A new page without title | The page takes the relation's name, made readable. |
tableView: false | The relation's page is removed, after the repeat. |
Writes are off until the project allows them
An external database is read-only to the tools until the project allows changes to it. The access of each connection sits on the dms-database entry of antelope.config.ts, the one the Data browser of the Database module edits:
"dms-database": {
config: {
externalConnections: {
erp: { access: "read-write" },
},
},
},
"read" is the default. The builder reads the access on every call, for the environment the project launched with, and merges the configuration as core does. A configuration it cannot load counts as "read".
On a connection that is not "read-write", these calls write nothing and answer an error that says how to allow changes:
builder_map_resourceswith awritable: trueresource that has a TableView.builder_add_block,builder_compose_pageandbuilder_configure_blockfor aResourceForminneworeditmode over a table of that connection.builder_add_blockandbuilder_compose_pagefor aTableViewover a table of that connection that still serves write routes. Map it again withwritable: falsefirst.
Mapping with writable: false, a ResourceForm in view mode, and every read tool keep working.
What the agent sees of the access
builder_analyse_database and builder_mapping answer access, "read" or "read-write", beside their data. Each resource carries writes, what the database account may insert, update and delete in that relation. The proposal's database.writes sums it up as none, some or all.
{ "ok": true, "data": [{ "ref": "erp/sales/orders", "resource": { "relation": "sales.orders", "writes": { "insert": true, "update": true, "delete": false } } }], "changes": [], "access": "read" }
On a "read" connection, the agent proposes no add, edit or delete action, and maps every relation with writable: false.
Allow writes once the person agrees
builder_set_connection_access changes a connection's access. The agent calls it only after the person agreed in the conversation, since it changes what the dashboard can write to their database:
{ "connection": "erp", "access": "read-write" }
The first call writes nothing and answers the planned change. The repeat writes config.externalConnections.<connection>.access on the dms-database entry of antelope.config.ts, and answers the new access. The builder reads it on its next call. The running backend applies it to the write routes after its restart, which ajs project dev does by itself when antelope.config.ts changes.
| Case | error.code |
|---|---|
| No catalog connection has that id. | not_found |
The project has no dms-database module. | invalid_config |
read-write, while the database account may write to no table. | invalid_config |
read-write, while the database's catalog does not answer. | invalid_config |
Lowering an access to "read" always works. A relation the account may not write stays read-only after the access is "read-write". builder_map_resources maps it with writable: false and a relation_read_only warning.
Other paths never raise an access
builder_configure_project never raises an access to "read-write". It refuses a step that would, unless the entry already holds the literal "read-write", and the refusal names builder_set_connection_access. Keeping, lowering or removing an access works.
A person can also allow writes with the Read & write switch of the Database module's Data browser, or in the assistant's connect step.
Connect a database
A builder_configure_project batch that connects a database registers the connection as { access: "read" }. Before it runs, the agent asks the person whether the dashboard may only read that database or also change its rows. For read and write, the agent calls builder_set_connection_access once the restarted project lists the connection in database_connections.
An agent never writes a database address. A connection runs only on a URL the person typed or confirmed, so builder_configure_project refuses a step that writes a server or an account into a driver's config:
| Driver | Refused under config |
|---|---|
@antelopejs/postgres | url, and pool.connectionString |
@antelopejs/mysql | url, and the pool host, port, socket, user and password keys |
@antelopejs/mongodb | url, and the credential, client certificate and proxy keys under options, plus srvServiceName and autoEncryption |
@antelopejs/rethinkdb | url, and server, host, port, user and password under pool and connection, plus pool.servers |
The refusal names the field to use instead, env: { url: "<VARIABLE>" }, which maps the variable that holds the URL. The person sets its value in the project's .env, or in the assistant's connect step.
An agent also never builds a block that sends the person's writes outside the page's own data API. See Requests a built block sends.