{"title":"AL MCP server","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/al-agent-tools/al-mcp-server/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/al-agent-tools/al-mcp-server, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/al-agent-tools/al-mcp-server","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn about the AL MCP Server, a standalone Model Context Protocol (MCP) server that exposes AL development tools for headless environments and CI/CD pipelines.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":2,"title":"System requirements","slug":"system-requirements","at":525,"chars":231},{"level":2,"title":"Starting the server","slug":"starting-the-server","at":756,"chars":1130},{"level":3,"title":"STDIO transport (recommended for most agents)","slug":"stdio-transport-recommended-for-most-agents","at":1036,"chars":564},{"level":3,"title":"HTTP transport","slug":"http-transport","at":1600,"chars":286},{"level":2,"title":"Available tools","slug":"available-tools","at":1886,"chars":1328},{"level":2,"title":"Configuring an agent to use the AL MCP Server","slug":"configuring-an-agent-to-use-the-al-mcp-server","at":3214,"chars":535},{"level":2,"title":"Calling a tool","slug":"calling-a-tool","at":3749,"chars":905},{"level":2,"title":"Authentication","slug":"authentication","at":4654,"chars":747},{"level":2,"title":"Common automation workflows","slug":"common-automation-workflows","at":5401,"chars":904},{"level":3,"title":"CI/CD validation pipeline","slug":"cicd-validation-pipeline","at":5432,"chars":374},{"level":3,"title":"Full build and deploy to sandbox","slug":"full-build-and-deploy-to-sandbox","at":5806,"chars":262},{"level":3,"title":"Code quality gate (AppSourceCop)","slug":"code-quality-gate-appsourcecop","at":6068,"chars":237},{"level":2,"title":"Session behavior","slug":"session-behavior","at":6305,"chars":567},{"level":2,"title":"Related information","slug":"related-information","at":6872,"chars":440}],"text":"Applies to: AL Language extension 17.0 and later\nThe AL MCP Server is a standalone Model Context Protocol (MCP) server that exposes AL development tools-building, compiling, publishing, symbol search, diagnostics, and more-to any MCP-compatible AI agent. It runs as a separate process and doesn't require Visual Studio Code.\nThis makes it possible to integrate AL development operations into CI/CD pipelines, chat-based agent workflows, and custom automation tooling using any agent that supports the Model Context Protocol.\n## System requirements\n .NET 8 runtime\n AL Language extension installed (provides the altool binary)\n Network access to a Business Central environment (for tools that connect to a server, such as al_publish and al_downloadsymbols)\n## Starting the server\nYou can pass one or more AL project paths when you start the server. Wrap each path in double quotes. If you don't specify a project path, no project is loaded. Add a project later with the al_addproject tool before you use tools that operate on a project.\n### STDIO transport (recommended for most agents)\n```shell\naltool launchmcpserver \"C:\\<ProjectFolder>\" --transport stdio\n```\nTo load multiple projects, specify each project path as a separate argument:\n```shell\naltool launchmcpserver \"C:\\<ProjectFolder1>\" \"C:\\<ProjectFolder2>\" --transport stdio\n```\nThe server reads JSON-RPC requests from stdin and writes responses to stdout. All diagnostic log output is written to stderr and should be captured separately. The server shuts down cleanly when stdin reaches EOF or when the process receives a termination signal.\n### HTTP transport\n```shell\naltool launchmcpserver \"C:\\<ProjectFolder>\" --transport http --port 5010\n```\nThe server listens for HTTP requests on the specified port. Use this transport for agents that connect over a network or for scenarios where launching a subprocess isn't practical.\n## Available tools\nThe following tools are exposed by the AL MCP Server. Tools marked MCP only aren't available in the Visual Studio Code Language Model Tools API.\nTool|Description\nal_build<al-tool-build>|Build the AL project and generate the `.app` package.\nal_compile<al-tool-compile>|Validate AL code without generating an `.app`. Faster than a full build.\nal_publish<al-tool-publish>|Publish the extension to a Business Central cloud or on-premises environment.\nal_downloadsymbols<al-tool-download-symbols>|Download dependent symbol packages from a BC environment or global sources.\nal_symbolsearch<al-tool-symbol-search>|Search AL symbols across the project and its dependencies, or on the connected environment.\nal_getdiagnostics<al-tool-get-diagnostics>|Retrieve compilation diagnostics with filtering.\nal_getnextobjectid<al-tool-get-next-object-id>|Allocate the next free AL object IDs before scaffolding a new object.\nal_getpackagedependencies<al-tool-get-package-dependencies>|List the project's declared app.json dependencies. MCP only.\nal_addproject|Add an AL project to the server workspace after startup. MCP only.\nal_auth_login<al-tool-auth#al_auth_login>|Authenticate to Microsoft Entra ID for cloud operations. MCP only.\nal_auth_logout<al-tool-auth#al_auth_logout>|Clear cached authentication tokens. MCP only.\n## Configuring an agent to use the AL MCP Server\nThe exact configuration depends on your agent. Most MCP-compatible agents accept a server configuration that specifies the command to launch. The example below shows a typical configuration in JSON format:\n```json\n{\n  \"mcpServers\": {\n    \"al\": {\n      \"command\": \"altool\",\n      \"args\": [\"launchmcpserver\", \"C:\\\\<ProjectFolder>\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\nThe agent discovers available tools automatically by calling the MCP `tools/list` endpoint after the server starts.\n## Calling a tool\nTool calls follow the MCP JSON-RPC protocol. The agent sends a `tools/call` request with the tool name and its parameters.\nExample: compile the current workspace\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"al_compile\",\n    \"arguments\": {\n      \"onlyErrors\": true\n    }\n  }\n}\n```\nExample: search for symbols\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"al_symbolsearch\",\n    \"arguments\": {\n      \"parameters\": {\n        \"query\": \"Post\",\n        \"filters\": {\n          \"kinds\": [\"Codeunit\"],\n          \"scope\": \"project\"\n        }\n      }\n    }\n  }\n}\n```\n> NOTE\n> The al_symbolsearch tool accepts query and filters either at the top level or under a parameters key. The example uses the wrapper for compatibility with existing clients. Other tools accept their parameters at the top level.\n## Authentication\nWhen a tool needs to connect to a Business Central cloud environment, the AL MCP Server uses browser-based interactive authentication via Microsoft Authentication Library (MSAL). Tokens are cached securely on disk and reused across calls.\nRecommended authentication workflow:\n1. Before the first cloud operation in a session, call al_auth_login with your tenant and environment details.\n2. The server opens a browser window for Microsoft Entra ID sign-in.\n3. After sign-in, the token is cached. All subsequent tool calls in the session reuse it automatically.\n4. When finished, call al_auth_logout to clear the cache.\nFor on-premises Business Central deployments that use Windows authentication, no explicit sign in is required.\n## Common automation workflows\n### CI/CD validation pipeline\n```shell\n# 1. Start the MCP server (managed by the CI agent)\naltool launchmcpserver \"C:\\<ProjectFolder>\" --transport stdio\n\n# The agent then calls tools in sequence:\n# al_downloadsymbols  (refresh symbols from global sources)\n# al_compile          (validate — fast, no .app output)\n# al_getdiagnostics   (fail the pipeline if errors exist)\n```\n### Full build and deploy to sandbox\n```shell\n# The agent calls:\n# al_auth_login       (authenticate to the cloud environment)\n# al_downloadsymbols  (refresh symbols)\n# al_build            (produce the .app package)\n# al_publish          (deploy to sandbox)\n```\n### Code quality gate (AppSourceCop)\n```shell\n# The agent calls:\n# al_compile with enableCodeAnalysis=true, codeAnalyzers=[\"${AppSourceCop}\"]\n# al_getdiagnostics filtered by areas=[\"AppSourceCop\"]\n# (fail if any errors are returned)\n```\n## Session behavior\nThe AL MCP Server maintains a compilation session during the process lifetime. The session is initialized when the server starts and is shared across all tool calls. This means that symbol state and compilation caches are preserved between calls, which improves performance for sequential operations such as compile -> diagnose -> fix -> recompile.\nUse the al_addproject tool to load more projects after the server starts. When the server has multiple projects, use the projectPath parameter on individual tool calls to target a specific project.\n## Related information\nAI agent tools overview<al-agent-tools-overview>\nAL Language Model Tools for Visual Studio Code<al-language-model-tools-vscode>\nal-tool-build\nal-tool-compile\nal-tool-publish\nal-tool-download-symbols\nal-tool-symbol-search\nal_getdiagnostics<al-tool-get-diagnostics>\nal_getnextobjectid<al-tool-get-next-object-id>\nal_getpackagedependencies<al-tool-get-package-dependencies>\nal_auth_login and al_auth_logout<al-tool-auth>"}