MCP server
The MCP server that AntelopeJS DMS serves in development, how Claude Code and Codex connect to it, its tools, Safe mode and its configuration.
Under ajs project dev, @antelopejs/dms serves an MCP server named dms. Claude Code or Codex in your project connects to it and gets the builder, database, page and mockup tools that the DMS AI assistant uses. No other module is needed. Nothing of the server loads in production.
Your agent also needs the antelopejs plugin to know when and how to call these tools. See Install the plugin.
Agent entries
Each start in development adds a dms server to two project files, and creates them when they are missing. Neither entry holds a machine path or a secret, so you can commit both.
{
"mcpServers": {
"dms": {
"command": "node",
"args": ["node_modules/.cache/dms/mcp-bridge.cjs"]
}
}
}
Run claude in the project root and approve the dms server. The tools then appear as mcp__dms__builder_catalog and the like.
The DMS writes the entry only when it is missing. It keeps your other servers and never changes a dms entry you wrote.
[mcp_servers.dms]
command = "node"
args = ["-e", "require('.cache/dms/mcp-bridge.cjs')"]
Codex reads .codex/config.toml only in a project you trust. Run codex in the project and accept the trust prompt. codex mcp list then shows dms. The entry works from any folder of the project.
The DMS appends the table only when no dms server is declared, and keeps the rest of the file as it is. It leaves alone a file that is not TOML, or that declares mcp_servers as an inline table, and logs why.
When the backend is down, a tool call answers an error that says to start it with ajs project dev. The next call after the start works.
Tools
Each tool has an effect, which Safe mode reads.
| Effect | Tools |
|---|---|
read | 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, database_connections, database_project, database_relations, database_describe, database_profile, list_pages, navigate_to_page, page_verify, typecheck, query_logs, mockup_annotations, mockup_read_spec |
builder | 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_configure_column_groups, builder_remove_field, builder_add_query, builder_configure_query, builder_remove_query, builder_map_resources, builder_set_theme, builder_create_theme_layer, mockup_write_spec, mockup_patch_spec, mockup_resolve_annotation, mockup_from_page, mockup_apply_to_page |
project | builder_configure_project, builder_set_connection_access, builder_delete_resource |
- A
readtool changes nothing in the project. - A
buildertool edits pages, resources, queries, the theme or mockups. The builder typechecks each edit before it writes it. - A
projecttool changes the project past its sources:antelope.config.ts, what the dashboard may write to an external database, or the data of a deleted resource's table.
Some tools behave differently from the dashboard chat:
| Tool | Behaviour |
|---|---|
navigate_to_page | Moves the open dashboard tab of each browser to a registered page. Answers the page's URL and how many browsers moved, or the closest routes when the path is not a page. |
page_verify | Opens pages in a headless Chromium and answers a report. See Verify a page. |
typecheck | Runs tsc --noEmit in the project root, or in the loaded module that target names. |
builder_analyse_database | Answers compactly: per relation its screen, rows, columns, types and relations. Its detail input names the relations ("schema.name") to answer in full. Past 30 tables it adds groups: the tables by schema, or by name prefix when there is a single schema, so the user picks or skips a group whole before refining inside it. |
mockup_from_page, mockup_apply_to_page | Convert a page into a mockup and write it back. See Live page mockups. |
database_* | Read every catalog connection the project declares. Pass a connection id from database_connections to the others. database_project answers what a builder_configure_project batch needs to connect a database. |
A database driver answers its catalog in development only. On a backend started with ajs project start, database_connections lists the connection with an error until the driver's entry sets config.catalog.enabled.
Safe mode
Safe mode limits a session to the read and builder tools. tools/list leaves out the project tools, and a call to one answers an error. The server enforces it, whatever the client's own permissions allow.
Turn it on for the whole project with mcp.access: "safe". The default is "full".
A client can also ask for Safe mode for its own session by starting the bridge with --access=safe:
node node_modules/.cache/dms/mcp-bridge.cjs --access=safe
The session gets the stricter of the bridge's access and mcp.access. A client can narrow its access, never widen it.
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_set_connection_access, with the change toantelope.config.tsit 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. Each process the client starts from .mcp.json is one session.
The last text block of a waiting answer is the JSON {"code":"confirmation_required"}. A client that asks the person itself can rely on that code, not on the prose before it. A confirmed call that then fails ends with {"code":"confirmation_consumed"}, and the next identical call waits again.
Keep the mcp__dms__builder_* tools out of your client's allow list, so the client also asks you before the repeat.
Column presentation
A mockup table's column presentation goes into a resource's @Column through builder tools alone, so it works in Safe mode. builder_add_field, builder_configure_field, builder_create_resource and the fields of builder_map_resources take:
| Input | Written as |
|---|---|
display: { type, options? } | display: new DefaultDisplays.<Class>(options), with its import. type is one of identity, pills, relative_date, indicator, status_pill, two_line, progress, sparkline, duration, bytes, string and mono. |
group | The id of the form group the field joins. |
isVisible, size, cellWrap, description | The @Column options of the same names. |
The builder checks a display's options against its class and refuses a wrong one with invalid_config, such as the two_line display refuses its options: options.subField: Expected string, received number. builder_configure_field replaces an option you send and removes one you send as null.
builder_configure_column_groups { resource, groups } writes the class's @ColumnGroup(id, { label, description?, orientation?, order? }) decorators. A group you send replaces the one with its id, null removes it, and a group you leave out stays. builder_resource_structure reads every option back, with the groups as columnGroups.
Sidebar sections
The sidebar groups pages in two ways. A section is a header in the sidebar, such as the built-in Pages, with its pages under it. A category folds its pages under one entry inside a section. A mockup's categories are sections.
builder_create_categorymakes a category under itsparent, Pages (refpages) by default, and answers its ref, such aspages.billing. Withsection: true, it makes a section, whose ref is its name. Itsorderplaces it among Pages (1), Modules (2) and Settings (3).builder_configure_categorywithsection: trueturns a category directly under Pages into a section.section: falseturns it back. The pages keep their routes, and the answer gives the new ref.- To put a page in a section, pass the section's ref as the
categoryofbuilder_create_page, or of a resource inbuilder_map_resources. builder_list_pagesanswers{ pages, categories }. A section carriessection: true, and each page carries the ref of itssection.
Verify a page
page_verify takes a page, or a list of up to ten. A page is a route as list_pages answers it, a concrete route for a route with parameters, or a page's full id. The browser signs in as the platform owner, or with role, as a member who holds 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:
| Field | Content |
|---|---|
failures | One line per failed check. Read these first. |
render | Each block of the layout, present and inside the page width, and any sideways scrolling or overlap. |
data | The state each table, chart and KPI reports: ok, empty, error, loading, or needs_backend in a preview. |
errors | Console errors, uncaught exceptions and failed requests. |
interactions | Whether links answer, tabs select, and sorting and search change the page. Each form, and each form a New, Add, Create or Edit button opens, is submitted. It passes when it shows validation or sends its write. |
permissions | For each role of the workspace, whether it opens the page, and what a member with only that role saw. |
With mockup, the report compares the page with a page of mockups/<name>/spec.json. Each mockup block is paired with the page block at the same layout path, or with the one that draws the same component.
Every write the page tries during the check is held back, unless submit is true. Then a form whose empty submit showed validation is filled with sample values and submitted for real.
page_verify takes no screenshot, because an image would show the values of the page's rows to the AI client. The first call downloads the headless Chromium that playwright-core pins, about 330 MB, once per machine. playwright-core is an optional dependency of @antelopejs/dms.
How the bridge reaches the backend
The bridge is a stdio MCP server. It relays each JSON-RPC message to POST /dms/mcp on the backend and writes the answer back.
- Each start of the backend draws a new credential. The DMS writes it, with the route's URL, to
node_modules/.cache/dms/mcp.jsonwith file mode0600. The launchermcp-bridge.cjssits beside it. Neither file is committed. - The bridge reads that file for every message, so it reaches a restarted backend without a reconnect.
- The route answers only a caller on the same machine that holds this start's credential. It refuses a request that carries a header a proxy adds, such as
X-Forwarded-For,Forwarded,ViaorCF-Connecting-IP. - The route reads up to 1 MiB per message, and answers
413past it.
The credential never leaves the machine. The bridge sends requests to mcp.backendUrl, else to apiBaseUrl when its host is loopback, such as the default http://127.0.0.1:5010. When neither is loopback, the DMS writes no credential, no launcher and no agent entry, and logs a warning that names mcp.backendUrl.
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" or "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. |
mcp.codexConfig | boolean | true | Adds the dms server to .codex/config.toml when none is declared. |
mcp.backendUrl | string | apiBaseUrl, when its host is loopback | The origin the bridge sends its requests and credential to. A host that is not loopback is refused. |
A project whose apiBaseUrl points at a public host needs mcp.backendUrl. Set it to the api module's local origin:
dms: {
config: {
mcp: {
backendUrl: "${@api.API_LOCAL_BASE_URL}",
access: "safe",
},
},
},
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 a change.
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 works the same way for .codex/config.toml.