[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationMCP server

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.

.mcp.json json
{
  "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.

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.

EffectTools
readbuilder_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
builderbuilder_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
projectbuilder_configure_project, builder_set_connection_access, builder_delete_resource
  • A read tool changes nothing in the project.
  • A builder tool edits pages, resources, queries, the theme or mockups. The builder typechecks each edit before it writes it.
  • A project tool 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:

ToolBehaviour
navigate_to_pageMoves 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_verifyOpens pages in a headless Chromium and answers a report. See Verify a page.
typecheckRuns tsc --noEmit in the project root, or in the loaded module that target names.
builder_analyse_databaseAnswers 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_pageConvert 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:

terminal
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_field and builder_remove_query.
  • builder_configure_project, with the changes its dry run plans.
  • builder_set_connection_access, with the change to antelope.config.ts it 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:

InputWritten 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.
groupThe id of the form group the field joins.
isVisible, size, cellWrap, descriptionThe @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.

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_category makes a category under its parent, Pages (ref pages) by default, and answers its ref, such as pages.billing. With section: true, it makes a section, whose ref is its name. Its order places it among Pages (1), Modules (2) and Settings (3).
  • builder_configure_category with section: true turns a category directly under Pages into a section. section: false turns 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 category of builder_create_page, or of a resource in builder_map_resources.
  • builder_list_pages answers { pages, categories }. A section carries section: true, and each page carries the ref of its section.

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:

FieldContent
failuresOne line per failed check. Read these first.
renderEach block of the layout, present and inside the page width, and any sideways scrolling or overlap.
dataThe state each table, chart and KPI reports: ok, empty, error, loading, or needs_backend in a preview.
errorsConsole errors, uncaught exceptions and failed requests.
interactionsWhether 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.
permissionsFor 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.json with file mode 0600. The launcher mcp-bridge.cjs sits 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, Via or CF-Connecting-IP.
  • The route reads up to 1 MiB per message, and answers 413 past 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

KeyTypeDefaultPurpose
mcp.enabledbooleanThe runtime's development modeServes 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.mcpJsonbooleantrueAdds the dms server to .mcp.json when the entry is missing.
mcp.codexConfigbooleantrueAdds the dms server to .codex/config.toml when none is declared.
mcp.backendUrlstringapiBaseUrl, when its host is loopbackThe 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:

antelope.config.ts ts
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.