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

Registers a new AL object and returns its assigned ID.

Parameter	Type	Description
appId	UUID	The id from your extension's app.json
objectType	see below	AL object type
objectName	string, ≤ 30 chars	Object name, e.g. ART CU Demo Data

Returns the object ID as text, e.g. 50061. Calling it again with the same name returns the same ID rather than allocating a new one.

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": "..."
      }
    }
  }
}

npm run typecheck checks types without emitting. npm run build cleans dist/ first, and also runs automatically on npm pack and npm publish.