MCP server
The MCP server the DMS serves in development, so Claude Code or Codex in your project gets the builder, database and page tools of the dashboard assistant.
Under ajs project dev, @antelopejs/dms serves an MCP server. A coding agent you start in the project, such as Claude Code or Codex, reaches it through a stdio bridge. Claude Code launches the bridge from the project's .mcp.json, and Codex from the project's .codex/config.toml. The agent gets the builder tools, the database tools and the page tools of the dashboard assistant, with no other module installed. Nothing of the server loads in production.
The agent entries
Claude Code
Each start in development adds a dms server to the project's .mcp.json, and creates the file when there is none:
{
"mcpServers": {
"dms": {
"command": "node",
"args": ["node_modules/.cache/dms/mcp-bridge.cjs"]
}
}
}
The DMS writes the entry only when it is missing. It keeps the other servers, never changes a dms entry you wrote, and leaves a .mcp.json that is not a JSON object of servers alone. The file is printed the way oxfmt and Prettier print it. It holds no machine path and no secret, so you can commit it.
Run claude in the project root and approve the dms server. The tools then read mcp__dms__builder_catalog and the like.
Codex
Each start in development also adds a dms server to the project's .codex/config.toml, and creates the file when there is none:
[mcp_servers.dms]
command = "node"
args = ["-e", "require('.cache/dms/mcp-bridge.cjs')"]
Codex starts the server in the folder you run it from. Node finds the launcher in the nearest node_modules, so the entry works from any folder of the project.
The DMS appends the table only when no dms server is declared. It keeps the rest of the file as it is, comments included, and leaves a file that is not TOML, or that declares mcp_servers as an inline table, alone and logs why. The entry holds no machine path and no secret, so you can commit it.
Codex reads .codex/config.toml only in a project you trust. Run codex in the project and accept the trust prompt, then codex mcp list shows dms.
How the bridge reaches the backend
The bridge is a stdio MCP server. It relays each JSON-RPC line to POST /dms/mcp on the backend and writes the answer back.
- Each start draws a new credential. The DMS writes it, with the route's URL, to
node_modules/.cache/dms/mcp.json, with file mode0600. The launchermcp-bridge.cjssits beside it and loads the bridge of the installed@antelopejs/dms. Neither file is committed. - The bridge reads that file for every message, so a restarted backend is reached without a reconnect.
- The route URL starts with
mcp.backendUrl. Set it to the api module's same-host origin,${@api.API_LOCAL_BASE_URL}, as Configuration shows. Without it, the bridge usesapiBaseUrlonly when its host is loopback, such as the defaulthttp://127.0.0.1:5010.apiBaseUrlis the public backend URL, so a project that points it at a public host needsmcp.backendUrl. - The credential never leaves the machine. When neither URL is loopback, the DMS writes no credential, no launcher, no
.mcp.jsonentry and no.codex/config.tomlentry, and logs one warning that namesmcp.backendUrl. The bridge also refuses to send a request to a host that is not loopback, and answers an error that namesmcp.backendUrl. - The route answers only a caller on the backend's machine that came straight to it, holding the credential of this start. It refuses a request that carries a header a proxy adds:
X-Forwarded-For,Forwarded,X-Forwarded-Host,X-Forwarded-Proto,X-Real-IP,Via,True-Client-IPorCF-Connecting-IP. The DMS frontend server addsX-Forwarded-ForandForwardedto every request it relays. - The route reads up to 1 MiB per message and answers
413past it.
When the backend is down, a call answers an error that says to start it with ajs project dev. The next call after the start works.
Tools
| Tool | Effect |
|---|---|
builder_catalog, builder_list_pages, builder_page_structure, builder_refresh, builder_list_resources, builder_resource_structure, builder_query_templates, builder_preview_query, builder_analyse_database, builder_mapping, builder_get_theme | read |
builder_create_page, builder_configure_page, builder_delete_page, builder_add_block, builder_compose_page, builder_configure_block, builder_configure_table_view, builder_move_block, builder_remove_block, builder_create_category, builder_configure_category, builder_delete_category, builder_create_resource, builder_add_field, builder_configure_field, builder_remove_field, builder_add_query, builder_configure_query, builder_remove_query, builder_map_resources, builder_set_theme, builder_create_theme_layer | builder |
builder_configure_project, builder_delete_resource | project |
database_connections, database_project, database_relations, database_describe, database_profile | read |
list_pages, navigate_to_page, preview_blocks, page_verify, typecheck, query_logs | read |
mockup_annotations | read |
mockup_write_spec, mockup_patch_spec, mockup_resolve_annotation, mockup_from_page, mockup_apply_to_page | builder |
A read tool changes nothing in the project. A builder tool edits pages, resources, queries and the theme through the builder, which typechecks each edit before it writes it. A project tool changes the project past its sources: antelope.config.ts, or the data of a deleted resource's table.
Some tools differ from the dashboard chat:
navigate_to_pageresolves a registered page and moves the open dashboard tab of each browser to it: the tab that holds the browser's realtime connection. It answers the page's dashboard URL,<clientBaseUrl><path>, and how many browsers moved, or the closest known routes when the path is not a page.preview_blocksrenders nothing. It checks the block tree against the block types the DMS registers and the preview's limits, then answers what it checked. It refuses a sketch the mockup compiler refuses, by the same allowlist (see Sketch check).page_verifyopens pages in a headless Chromium and answers a JSON report, so an agent proves a page works, not only that it builds. See Verifying a page.typecheckrunstsc --noEmitin the project root by default, or in a loaded module named bytarget.mockup_from_pageturns an existing page into a mockup, as the dashboard's "Edit as mockup" does. It answers an error unless the backend runs in development, where/mockupexists. Its spec page records the page inlivePage: building the mockup updates that page and never creates another.mockup_apply_to_pagebuilds such a spec page back into its live page in one write. See Build it back into the page. It answers an error unless the backend runs in development.- The
database_*tools read every catalog connection the project declares for the DMS, each through its own provider. Pass a connection id fromdatabase_connectionsto the others.database_projectanswers what abuilder_configure_projectbatch that connects a database needs, asGetDatabaseProjectdoes: the module ids to write, the modules to pin, and the driver package and range of each engine the project can start. A driver answers its catalog in development only, so on a backend run withajs project start,database_connectionslists the connection with anerroruntil the driver's entry setsconfig.catalog.enabled.
What the tools show of a connected database
The tools answer the shape of a connected database, never a value from its rows. See Connected database values.
Verifying a page
page_verify takes a page (a route as list_pages answers it, a concrete one for a route with parameters, or a page full id), or a list of up to ten. It signs the browser in through the same session handoff a password change uses, as the platform owner or, with role, as a member holding only that role. Each page is drawn at desktop (1440×900) and mobile (390×844) unless viewports names others.
The report holds, for each page:
failures: one line per failed check. Read these first.render: each block the layout serves, present and drawn inside the page width, sideways scrolling and overlapping blocks, all read from the page's DOM.data: the state each table, chart and KPI reports:ok,empty,error,loading, orneeds_backendin a preview.errors: console errors, uncaught exceptions and failed requests of the browser. A request the dashboard makes while rendering on the server shows as the block'serrorstate, not here.interactions: links answer, tabs select, and sorting and searching refetch or change the page. Each form on the page, and each one aNew,Add,CreateorEditbutton opens, is submitted: it passes when it shows validation, or when it sends its write, on submit or on change. A form with no enabled submit control is first given a value in a text field. A form whose save no text field triggers is reportednot checked.permissions: for each role of the workspace, whether its grants open the page, and what the browser saw signed in as a member holding only that role. A role that no member holds alone isnot_checked.
With mockup, the page is compared with a page of mockups/<name>/spec.json drawn by the /mockup viewer: each mockup block is paired with the page block at the same layout path or drawing the same component. The viewer is owner-only, so it opens signed in as the platform owner, whatever role the page is checked as.
Every write the page tries while it is checked is held back, unless submit is true: then a form whose empty submit showed validation is filled with sample values and submitted, and its write goes through.
page_verify takes no screenshot, of the page or of the mockup. A screenshot would show the values of the page's rows, and a mockup block can read a live route, so the AI client could read them from the image. The first call downloads the headless Chromium playwright-core pins into Playwright's own cache, about 330 MB, once per machine; the backend log says so. playwright-core is an optional dependency of @antelopejs/dms, loaded only when the tool runs.
Calls that wait for a repeat
An MCP client has no confirmation card. These calls answer what they would do and run nothing the first time:
- a deletion:
builder_delete_page,builder_delete_category,builder_delete_resource,builder_remove_fieldandbuilder_remove_query; builder_configure_project, with the changes its dry run plans;builder_map_resources, when its preview finds a page to remove.
Show the answer to the person you work for. The same call, repeated unchanged within 10 minutes by the same MCP session, runs once. Each process the client starts from .mcp.json is one session, so another session's identical call waits again. A mapping whose pages to remove changed in between is a new call and waits again.
A client that asks the person itself tells the answer apart by its last text block, which is the JSON {"code":"confirmation_required"}. The prose before it can change wording, and the code does not. A call refused because its client sent no session carries no code, since repeating it never runs it. A confirmed call that then fails ends with {"code":"confirmation_consumed"} after the builder's error: the confirmation is spent, so the next identical call waits again. A call that fails before the gate, such as a refused preview, carries no code and holds nothing. Keep the mcp__dms__builder_* tools out of your client's allow list too, so the client asks before the repeat.
Writes to an external database
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 when the entry is absent. Before each of these calls, the builder loads the project configuration with core's own ConfigLoader for the environment the project launched with, so it reads what dms-database receives: the entry, that environment's member of environments, antelope.dms-database.json and envOverrides, merged in core's order. A configuration that cannot be loaded counts as "read", and the refusal says why. On a connection that does not resolve to "read-write", these calls answer an error that names the connection, the place that keeps it read-only and how to allow changes, and write nothing:
builder_map_resourceswith awritable: trueresource that has a TableView, which would serve create, edit and delete routes on the table;builder_add_block,builder_compose_pageandbuilder_configure_blockfor aResourceForminneworeditmode over a table mapped from that connection;builder_add_blockandbuilder_compose_pagefor aTableViewover a table mapped from 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. The builder reads the access on every call, so a change applies without a restart.
An agent never raises an access. builder_configure_project, the only tool that writes project or module configuration, refuses a step that sets config.externalConnections.<id>.access to "read-write" where the module's entry in antelope.config.ts does not already hold the literal "read-write" (an expression, a variable, a template or an environment that grants it does not count, since the step writes the entry every environment reads), to anything else but "read", supplies it from a variable, or rebinds a variable envOverrides maps to it, whatever mcp.access is. Keeping, lowering or removing an access works, so a step may restate the connections it does not change. A person grants writes with the Read & write switch of the Database module's Data browser, or in the assistant's connect step: the dms-database route PUT /api/database/connections/<id>/access and the assistant's POST /database/project write through the builder interface, which leaves the access as asked.
An agent never writes a database address either. A database connection runs only on a URL the person typed or confirmed, so builder_configure_project refuses a step that writes any value where a database driver's config takes a server or an account. A module is a driver when its id, a step's source or its entry in antelope.config.ts names a driver package, directly or through a local folder's package.json. A module whose entry or source the builder cannot read, or whose source is of another type such as git, counts as any driver. Members match whatever their case.
| Driver | Refused under config |
|---|---|
@antelopejs/postgres | url, and pool.connectionString, which pg reads before the URL |
@antelopejs/mysql | url, and pool.host, pool.port, pool.socketPath, pool.user, pool.password, pool.password1 to pool.password3 and pool.passwordSha1, which mysql2 reads before the URL |
@antelopejs/mongodb | url, and under options the credentials (auth, authMechanism, authMechanismProperties, authSource), the client certificate (tlsCertificateKeyFile, tlsCertificateKeyFilePassword, cert, key, pfx, passphrase), the proxy (proxyHost, proxyPort, proxyUsername, proxyPassword), 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 never builds a block that sends the person's writes outside the page's own data API either: see Requests a built block sends.
Safe mode
Safe mode is a tool scope, set with mcp.access. With access: "safe", the server lists and runs only the read and builder tools: tools/list leaves out builder_configure_project and builder_delete_resource, and a call to either answers an error. The server enforces it, whatever the client's own permission settings allow. The default is "full", which serves every tool.
Configuration
| Key | Type | Default | Purpose |
|---|---|---|---|
mcp.enabled | boolean | The runtime's development mode | Serves the route and writes the bridge files. true serves them in any mode. false turns them off in development too. |
mcp.access | "safe" | "full" | "full" | The tools a session may list and call. |
mcp.mcpJson | boolean | true | Adds the dms server to .mcp.json when the entry is missing. false leaves the file alone. |
mcp.codexConfig | boolean | true | Adds the dms server to .codex/config.toml when none is declared. false leaves the file alone. |
mcp.backendUrl | string | apiBaseUrl, only when its host is loopback | The origin the bridge sends its requests and its credential to. Set it to ${@api.API_LOCAL_BASE_URL}. A host that is not loopback is refused. |
Point the bridge at the backend on your machine:
dms: {
config: {
mcp: { backendUrl: "${@api.API_LOCAL_BASE_URL}" },
},
},
The other keys go beside it:
dms: {
config: {
mcp: {
backendUrl: "${@api.API_LOCAL_BASE_URL}",
access: "safe",
mcpJson: false,
codexConfig: false,
},
},
},
A mcp value the DMS cannot read, such as access: "Safe", turns the server off and logs why. The DMS reads the key once, at module construction, so restart the backend after you change it. To stop the DMS from writing .mcp.json, set mcpJson: false and delete the dms entry. While mcpJson is on, a deleted entry comes back on the next start. codexConfig does the same for .codex/config.toml.