alrm-mcp

MCP server for AL ID Range Manager.

Lets an AI coding agent reserve AL object IDs the same way the ALRM VS Code extension does. When the agent is about to create a new AL object, it calls new_object, and the shared ALRM database in Business Central validates the name and hands back the next free object ID — so IDs stay unique across everyone working on the same extension.

Tools

new_object

Reserves the next free ID for a new AL object and validates its name.

| Parameter | Type | Description | | ------------ | ------------------ | ---------------------------------------------------------------------------- | | appId | UUID | The id from your extension's app.json | | objectType | enum, see below | AL object type, lowercase, as written in the declaration | | objectName | string, ≤ 30 chars | Name as it will appear in the declaration, unquoted, e.g. ART CU Demo Data |

Returns the reserved declaration as text, e.g. codeunit 50061 "ART CU Demo Data", so an agent making several calls at once can't mismatch an ID with the name it belongs to.

Calling it again with the same name in the same app returns the same ID rather than allocating a new one, which makes it safe to retry.

Object types that have no ID in AL — interface, controladdin, profile, entitlement, pagecustomization — come back as <NO-ID> instead.

objectType accepts:

codeunit, page, pageextension, pagecustomization, table, tableextension, query, report, reportextension, xmlport, enum, enumextension, permissionset, permissionsetextension, entitlement, profile, interface, controladdin

new_object_line

Reserves the next free ID for one new field in a table extension, or one new value in an enum extension.

| Parameter | Type | Description | | ------------ | ----------------------------------- | ----------------------------------------------------------------- | | appId | UUID | The id from your extension's app.json | | objectType | tableextension | enumextension | Type of the extension object the field or value is being added to | | objectId | integer | ID of the extension object itself, as returned by new_object |

Returns the field or value ID as text, e.g. 50004.

One call reserves one ID — there is no batch mode, so five new fields means five calls. Unlike new_object there is no name to key on, so every call allocates a new ID: don't call twice for the same field, and don't retry a call that may already have succeeded.

When two tables are linked by TransferFields, register the field only in the main table and reuse that ID in the other.

Requirements

• Node.js 20 or newer
• A Business Central environment with the ALRM extension installed
• Permission to sign in to that environment (see Authentication)

Configuration

{
  "mcpServers": {
    "alrm-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "alrm-mcp@latest"],
      "env": {
        "BC_TENANT": "{tenant}",
        "BC_ENVIRONMENT": "{environment}",
        "BC_COMPANY": "{company}"
      }
    }
  }
}

For Claude Code you can add it in one command:

claude mcp add alrm-mcp \
  --env BC_TENANT=contoso.com \
  --env BC_ENVIRONMENT=Production \
  --env BC_COMPANY=00000000-0000-0000-0000-000000000000 \
  -- npx -y alrm-mcp@latest

Environment variables

All three are required — the server exits immediately with a message naming whichever is missing.

| Variable | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | BC_TENANT | Your Microsoft Entra tenant — either the domain (contoso.com) or the tenant GUID. | | BC_ENVIRONMENT | The Business Central environment name as shown in the BC admin center, e.g. Production or Sandbox. | | BC_COMPANY | The company id (a GUID, not the display name). List them at https://api.businesscentral.dynamics.com/v2.0/{BC_TENANT}/{BC_ENVIRONMENT}/api/v2.0/companies. |

These are read only from the MCP client's env block — there is no .env file support, since the server is normally launched by the client rather than from a shell.

Two optional variables let you point the server at your own Entra app registration instead of the default public client:

| Variable | Default | Description | | ---------------- | -------- | ----------------------------------------------------------------------------------- | | ALRM_CLIENT_ID | built-in | Application (client) ID of a public client app registration. | | ALRM_TENANT | common | Authority tenant used for sign-in. Set this to restrict sign-in to a single tenant. |

Authentication

The first tool call signs you in using the OAuth 2.0 device code flow:

1. A browser tab opens at https://microsoft.com/devicelogin.
2. The device code is copied to your clipboard, and also printed to the server's stderr in case the clipboard or browser isn't available.
3. Paste the code, complete sign-in, and the tool call proceeds.

Afterwards the token cache is stored in your operating system's credential store — Keychain on macOS, DPAPI on Windows, Secret Service/libsecret on Linux — with a small index file at .alrm-cache.json in your home directory. Later sessions reuse it silently, including across restarts of the server and of your editor, so you should not see the browser again until the refresh token expires (roughly 90 days of inactivity).

To sign out, delete .alrm-cache.json and remove the alrm-mcp entry from your credential store. On macOS:

rm ~/.alrm-cache.json
security delete-generic-password -s alrm-mcp -a alrm-mcp

There is no logout command yet.

Platform notes

On Linux the server refuses to fall back to storing tokens in plaintext. On a headless machine with no Secret Service available, sign-in will fail rather than silently write an unencrypted token cache.

Troubleshooting

The server won't start / the client reports CONNECTION_CLOSED. Almost always a missing or misspelled environment variable. Run it directly to see the actual error, which the MCP client swallows:

BC_TENANT=contoso.com BC_ENVIRONMENT=Production BC_COMPANY=... npx -y alrm-mcp@latest

A healthy server prints MCP server running on stdio and waits.

Extension {id} not found! The appId from your app.json has not been registered in the ALRM database for this company. Register the extension first, using the VS Code extension or directly in Business Central.

A browser opened unexpectedly. That's the sign-in described above. It should happen once, not on every call — if it repeats, the token cache isn't being persisted; check the stderr output for a message about reusing the stored sign-in.

Development

git clone https://github.com/hiimnit/alrm-mcp.git
cd alrm-mcp
npm install
npm run build

Then point your MCP client at the local build instead of the published package:

{
  "mcpServers": {
    "alrm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/alrm-mcp/dist/index.js"],
      "env": {
        "BC_TENANT": "...",
        "BC_ENVIRONMENT": "...",
        "BC_COMPANY": "..."
      }
    }
  }
}