{"title":"Troubleshooting MCP Server for AL","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-debug-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/devenv-debug-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/devenv-debug-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 how to use the Troubleshooting MCP Server to analyze runtime state during debugging sessions with AI-powered insights in AL.","date":"2026-03-10","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Troubleshooting MCP Server for AL","slug":"troubleshooting-mcp-server-for-al","at":0,"chars":11539},{"level":2,"title":"When to use the Troubleshooting MCP Server","slug":"when-to-use-the-troubleshooting-mcp-server","at":555,"chars":630},{"level":2,"title":"Prerequisites","slug":"prerequisites","at":1185,"chars":261},{"level":2,"title":"Available tools","slug":"available-tools","at":1446,"chars":4193},{"level":3,"title":"To verify the Troubleshooting MCP Server is available","slug":"to-verify-the-troubleshooting-mcp-server-is-available","at":2036,"chars":129},{"level":3,"title":"Troubleshooting MCP Server tools","slug":"troubleshooting-mcp-server-tools","at":2165,"chars":136},{"level":3,"title":"Analyzing AL runtime errors with all tools","slug":"analyzing-al-runtime-errors-with-all-tools","at":2301,"chars":732},{"level":3,"title":"Get Stack Frames","slug":"get-stack-frames","at":3033,"chars":567},{"level":4,"title":"Example question - stack frames","slug":"example-question---stack-frames","at":3528,"chars":72},{"level":3,"title":"Get variables","slug":"get-variables","at":3600,"chars":898},{"level":4,"title":"Example questions - get variables","slug":"example-questions---get-variables","at":4369,"chars":129},{"level":3,"title":"Get source code","slug":"get-source-code","at":4498,"chars":623},{"level":4,"title":"Example question - get source code","slug":"example-question---get-source-code","at":5026,"chars":95},{"level":3,"title":"Add breakpoint","slug":"add-breakpoint","at":5121,"chars":518},{"level":4,"title":"Example question - add breakpoint","slug":"example-question---add-breakpoint","at":5552,"chars":87},{"level":2,"title":"Tips and best practices","slug":"tips-and-best-practices","at":5639,"chars":1180},{"level":3,"title":"Be specific in your requests","slug":"be-specific-in-your-requests","at":5779,"chars":159},{"level":3,"title":"Reference stack frame numbers","slug":"reference-stack-frame-numbers","at":5938,"chars":212},{"level":3,"title":"Combine multiple queries","slug":"combine-multiple-queries","at":6150,"chars":179},{"level":3,"title":"Use for complex scenarios","slug":"use-for-complex-scenarios","at":6329,"chars":233},{"level":3,"title":"Verify Copilot's findings","slug":"verify-copilots-findings","at":6562,"chars":257},{"level":2,"title":"Common use cases","slug":"common-use-cases","at":6819,"chars":823},{"level":3,"title":"Debugging test failures","slug":"debugging-test-failures","at":7133,"chars":131},{"level":3,"title":"Understanding error origins","slug":"understanding-error-origins","at":7264,"chars":119},{"level":3,"title":"Inspecting state across frames","slug":"inspecting-state-across-frames","at":7383,"chars":127},{"level":3,"title":"Analyzing system code behavior","slug":"analyzing-system-code-behavior","at":7510,"chars":132},{"level":2,"title":"Understanding frame IDs","slug":"understanding-frame-ids","at":7642,"chars":251},{"level":2,"title":"Variable display format","slug":"variable-display-format","at":7893,"chars":439},{"level":2,"title":"Limitations","slug":"limitations","at":8332,"chars":282},{"level":2,"title":"Comparison with traditional debugging","slug":"comparison-with-traditional-debugging","at":8614,"chars":543},{"level":2,"title":"Best practices for AL developers","slug":"best-practices-for-al-developers","at":9157,"chars":708},{"level":3,"title":"Do","slug":"do","at":9287,"chars":314},{"level":3,"title":"Don't","slug":"dont","at":9601,"chars":264},{"level":2,"title":"Troubleshooting","slug":"troubleshooting","at":9865,"chars":714},{"level":3,"title":"\"No debug session active\"","slug":"no-debug-session-active","at":9955,"chars":165},{"level":3,"title":"\"Frame ID not found\"","slug":"frame-id-not-found","at":10120,"chars":164},{"level":3,"title":"\"Source code unavailable\"","slug":"source-code-unavailable","at":10284,"chars":147},{"level":3,"title":"\"Empty variable list\"","slug":"empty-variable-list","at":10431,"chars":148},{"level":2,"title":"Advanced techniques","slug":"advanced-techniques","at":10579,"chars":688},{"level":3,"title":"Multi-frame variable tracking","slug":"multi-frame-variable-tracking","at":10602,"chars":169},{"level":3,"title":"Error context gathering","slug":"error-context-gathering","at":10771,"chars":167},{"level":3,"title":"Test failure root cause","slug":"test-failure-root-cause","at":10938,"chars":180},{"level":3,"title":"Performance investigation","slug":"performance-investigation","at":11118,"chars":149},{"level":2,"title":"Related information","slug":"related-information","at":11267,"chars":272}],"text":"# Troubleshooting MCP Server for AL\n> APPLIES TO: Business Central 2026 release wave 1 and later\nThe Troubleshooting Model Context Protocol (MCP) Server is an AI-powered debugging tool that allows you to analyze the runtime state of AL code during active debugging sessions using natural language queries. Unlike traditional debugging where you manually inspect variables and step through code, the Troubleshooting MCP Server enables GitHub Copilot to programmatically access stack frames, variables, source code, and breakpoints to help diagnose issues.\n## When to use the Troubleshooting MCP Server\nUse the Troubleshooting MCP Server when you want Copilot to help analyze:\n AL runtime errors - Understand how execution reached an error point\n Complex call stacks - Trace method calls across multiple application objects\n Variable state - Inspect variable values at specific execution points\n Logic flow issues - Understand why code took a particular path\n Breakpoint analysis - Set and analyze breakpoints programmatically\nTraditional debugging is still better for:\n Interactive step-through debugging\n Quick visual inspection of simple issues\n Learning code flow for the first time\n## Prerequisites\nThe following prerequisites are needed to run the Troubleshooting MCP Server:\n An active debugging session in Visual Studio Code\n Execution is paused at a breakpoint or error\n The AL Language extension installed\n GitHub Copilot Chat is enabled\n## Available tools\nThe Troubleshooting MCP Server is only available when debugging. When you start a debugging session and pause at a breakpoint or error, the Troubleshooting MCP Server automatically becomes available to GitHub Copilot. The Troubleshooting MCP Server should automatically be used when you ask Copilot questions related to debugging. If you want to ensure that the Troubleshooting MCP Server is being used, you can explicitly reference it in your questions. For example: `Use the Troubleshooting MCP Server to show me the call stack and variables when this error occurred.`\n### To verify the Troubleshooting MCP Server is available\n The Troubleshooting MCP Server is only active during a debug session.\n### Troubleshooting MCP Server tools\nThe Troubleshooting MCP Server supports four tools, which are described in the following sections.\n### Analyzing AL runtime errors with all tools\nThe best scenario for the Troubleshooting MCP Server is when the debugger stops at an AL runtime error. When you ask Copilot to analyze the error and suggest a fix, Copilot automatically calls all three diagnostic tools:\n Get stack frames - to trace the complete call stack and identify how execution reached the error\n Get variables - for each relevant stack frame to inspect variable state at the error point\n Get source code - for relevant frames to understand the code context that led to the error\nBased on this comprehensive analysis, Copilot can also suggest a code fix.\nAsk: `Use the Troubleshooting MCP Server to analyze the error at the current breakpoint and suggest a fix`\n### Get Stack Frames\nRetrieves the complete call stack showing how execution reached the current point. The tool returns detailed information about each stack frame and can be used for:\n Analyzing error flows\n Understanding method call hierarchy\n Identifying which test or entry point triggered execution\nThe tool returns:\n Method names\n Object IDs and types (Codeunit, Page, and so on)\n Object names\n Line numbers and statement spans\n Application information (app name, publisher, and version)\n#### Example question - stack frames\n`Analyze how this error occurred.`\n### Get variables\nInspects variable values at a specific stack frame. The tool can retrieve local and global variables, including complex types like Records and DotNet objects. It takes the frame ID as a parameter to specify which stack frame to analyze:\nframeid - The frame index (0 = current frame, 1 = caller, and so on)\nUse the tool for:\n Checking variable state at error point\n Understanding why a condition evaluated a certain way\n Verifying data flow between procedures\nThe tool returns:\n Variable names and values\n Type information\n Global versus local scope\n Nested children for complex types\n Database statistics (SQL latency, executes, and row reads)\n Special values like `<Uninitialized>`\nLearn more about frame IDs in the #understanding-frame-ids section.\n#### Example questions - get variables\n`Show me the value for the CallTreeProfilingNodes`\n`Analyze the error at this breakpoint`\n### Get source code\nRetrieves the source code for a specific stack frame. It takes the frame ID as a parameter to specify which stack frame's code to return:\nframeid - The frame index (optional, defaults to current)\nUse the tool for:\n Viewing code context for frames in system codeunits\n Understanding implementation details of called methods\n Analyzing code without switching files\nThe tool returns:\n Complete source code of the codeunit containing the frame\nLearn more about frame IDs in the #understanding-frame-ids section.\n#### Example question - get source code\n`Show me the source code at frame 2 in the call stack`\n### Add breakpoint\nProgrammatically adds a breakpoint during debugging. The tool takes the following parameters:\n ApplicationObjectId - The object number\n ApplicationObjectType - The object type (Codeunit, Page, and so on)\n LineNumber - Line number within the object\nUse the tool for:\n Setting conditional investigation points based on analysis\n Adding breakpoints to system code\n Automating breakpoint placement based on patterns\n#### Example question - add breakpoint\n`Add a breakpoint at line 42 in codeunit 50100`\n## Tips and best practices\nIn the next sections, you can find tips and best practices for using the Troubleshooting MCP Server effectively.\n### Be specific in your requests\n Don't ask \"What's wrong with my code?\"\n Ask \"Analyze how we got to this error using the Troubleshooting MCP Server\" instead.\n### Reference stack frame numbers\nWhen discussing specific frames, make sure to reference frame IDs, for example:\n `What are the variables at frame 1?`\n `Show me the source code for the GetProfilingNodes caller`\n### Combine multiple queries\nAsk Copilot to gather comprehensive information, such as:\n`Get the stack frames, then show me the variables at the error frame and the calling frame`\n### Use for complex scenarios\nThe Troubleshooting MCP Server works well for complex debugging scenarios, such as:\n Deep call stacks (5+ frames)\n Multiple codeunit interactions\n System/framework code analysis\n State corruption issues\n### Verify Copilot's findings\nThe Troubleshooting MCP Server provides raw data, but you should always verify the findings by checking:\n Variable values match your expectations\n Frame sequence makes logical sense\n Source code matches your repository version\n## Common use cases\nThe primary use case for the Troubleshooting MCP Server is analyzing AL runtime errors, where Copilot automatically invokes all three diagnostic tools-call stack, variables, and source code-to provide a comprehensive analysis and suggest a fix. It can also be used for the following scenarios.\n### Debugging test failures\nAsk: `Use the Troubleshooting MCP Server to show me the call stack and variables when this test fails`\n### Understanding error origins\nAsk: `Trace back through the stack frames to show me how execution reached this error`\n### Inspecting state across frames\nAsk: `Show me the RecordData variable values at the current frame and in the calling frame`\n### Analyzing system code behavior\nAsk: `Get the source code for the system codeunit frame and show me what parameters it received`\n## Understanding frame IDs\nFrame IDs represent the call stack position. Refer to the following table for details:\nFrame ID|Description\n0|Current execution point (where debugger is paused)\n1|Direct caller\n2|Caller's caller\nN|N levels up the call stack\n## Variable display format\nIn the Troubleshooting MCP Server, variables are shown with the following properties:\n Name - Variable identifier\n Value - Current value (or `<Uninitialized>`)\n TypeName - AL type (Integer, Text, Codeunit, Record, and so on)\n Children - For complex types (Records, DotNet objects)\nSpecial values include:\n `<Uninitialized>` - Variable declared but not assigned\n `<Database Statistics>` - SQL performance metrics\n## Limitations\nThe Troubleshooting MCP Server has the following limitations:\n Requires active debug session - it can't analyze past executions\n Frame-based - it's limited to current call stack; can't inspect other sessions\n No time travel - it can't go back to previous breakpoints\n## Comparison with traditional debugging\nFeature|Troubleshooting MCP Server|Traditional Debugger\nView call stack|Yes. Programmatic access|Yes. Visual panel\nInspect variables|Yes. Per Frame ID, showing variables for that call.|Yes. One frame at a time\nStep through code|No.|Yes.\nWatch variables|No.|Yes. (watch expressions)\nAI analysis|Yes. Automatic insights|No.\nComplex pattern detection|Yes.|No.\nSet breakpoints|Yes. Programmatic|Yes. Manual\nExport debug info|Yes. Via Copilot|No.\nMulti-frame analysis|Yes. Simultaneous|No. Manual switching\n## Best practices for AL developers\nThe following best practices can help you get the most out of the Troubleshooting MCP Server.\n### Do\nDo use the Troubleshooting MCP Server to:\n Use the Troubleshooting MCP Server for complex call stack analysis\n Ask Copilot to correlate variables across multiple frames\n Request pattern detection in error scenarios\n Get AI insights on why errors occurred\n Use for test failure analysis\n Use for fixing code\n### Don't\nDon't use the Troubleshooting MCP Server to:\n Replace all manual debugging with the MCP Server\n Expect it to modify execution flow\n Use for simple single-step investigations\n Rely on it without verifying findings\n Use when not in an active debug session\n## Troubleshooting\nThe following sections describe common issues and how to resolve them.\n### \"No debug session active\"\n Ensure that you've hit a breakpoint or an error\n Code must be paused in the debugger\n Check that the AL Language extension is running\n### \"Frame ID not found\"\n Frame IDs are zero-based indexes\n Check the stack depth first with Get Stack Frames\n Ensure that the frame still exists (hasn't returned)\n### \"Source code unavailable\"\n Some system frames might not return source\n Source might be from compiled .app files\n Try viewing variables instead\n### \"Empty variable list\"\n The frame might not have any local variables\n Check global variables in Frame 0\n The procedure might use parameters only\n## Advanced techniques\n### Multi-frame variable tracking\nTrack how a value changes through the call stack:\n `Show me the MyParameter variable at frames 0, 1, and 2 to see how it was modified`\n### Error context gathering\nGet comprehensive error context:\n `Get the stack frames, then show variables at the error frame and the source code of the calling method`\n### Test failure root cause\nUnderstand test failures:\n `This test is failing - use the Troubleshooting MCP Server to show me the full call stack from the test method to the error`\n### Performance investigation\nCheck database statistics:\n `Show me the database statistics at the current frame - how many SQL operations occurred?`\n## Related information\nDebugging in AL<devenv-debugging>\nSetting conditional breakpoints<devenv-debugging-conditional-breakpoints>\ndevenv-snapshot-debugging\ndevenv-attach-debug-next\ndevenv-debug-upgrade-install-code\nBusiness Central MCP Server overview<../ai/mcp-overview>"}