From 4dacbedc4c44a5e7497d36036d100519c81b4feb Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Fri, 10 Jul 2026 13:04:46 +0200 Subject: [PATCH 1/2] Add MCP configs + troubleshooting --- .../_index.md} | 82 +++++++++++++++++-- .../maia-plan-mcp/troubleshooting.md | 27 ++++++ 2 files changed, 104 insertions(+), 5 deletions(-) rename content/en/docs/developerportal/maia-plan/{maia-plan-mcp.md => maia-plan-mcp/_index.md} (74%) create mode 100644 content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md diff --git a/content/en/docs/developerportal/maia-plan/maia-plan-mcp.md b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md similarity index 74% rename from content/en/docs/developerportal/maia-plan/maia-plan-mcp.md rename to content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md index 799c08945c2..c4e0d9f7d09 100644 --- a/content/en/docs/developerportal/maia-plan/maia-plan-mcp.md +++ b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md @@ -2,7 +2,7 @@ title: "Maia Plan as MCP Server" url: /developerportal/maia-plan-mcp/ description: "Describes how to configure and use Maia Plan as an MCP server to retrieve project scope and solution content." -weight: 10 +weight: 2 --- ## Introduction @@ -74,13 +74,85 @@ The steps to configure your MCP client depend on the client you are using. The f To configure Claude Code to connect to the Maia Plan MCP Server, follow these steps: -1. Open your Claude Code configuration file. -2. Add the Maia Plan MCP Server to the list of available MCP servers. -3. Specify the server URL and authentication method (using the `MENDIX_TOKEN` environment variable). -4. Save the configuration file. +1. Open your Claude Code configuration file. This is available at the following paths: + + * Windows: `C:/Users//.claude/settings.json` + * macOS/Linux: `~/.claude/settings.json` + +2. Add the Maia Plan MCP Server to the list of available MCP servers and specify the server URL and authentication method (using the `MENDIX_TOKEN` environment variable). To do that, add the following server configuration: + + ```json + { + "servers": { + "mendixMcp": { + "type": "http", + "url": "https://plan.home.mendix.com/mcp-server/mcp", + "headers": { + "Authorization": "Bearer $MENDIX_TOKEN" + } + } + } + } + ``` + +3. Save the configuration file. +4. Verify the setup by following these steps: + + 1. Run the `claude mcp list` command. + 2. In the Claude Code chat, enter `Show my recent plans`. + 3. In the Claude Code chat, enter `Show details for plan UUID `. For detailed instructions, refer to the [Claude Code documentation](https://claude.com/docs/connectors/building/mcp). +#### Configuring Visual Studio Code Copilot + +To configure Visual Studio Code Copilot to connect to the Maia Plan MCP server, follow these steps: + +1. Open the Visual Studio Code MCP configuration file: + + * User-level: `C:/Users//AppData/Roaming/Code/User/mcp.json` + * Workspace-level (optional): `.vscode/mcp.json` + +2. Add the Maia Plan MCP Server to the list of available MCP servers and specify the server URL and authentication method (using the `MENDIX_TOKEN` environment variable). To do that, add the following server configuration: + + ```json + { + "servers": { + "mendixMcp": { + "type": "http", + "url": "https://plan.home.mendix.com/mcp-server/mcp", + "headers": { + "Authorization": "Bearer ${env:MENDIX_TOKEN}" + } + } + } + } + ``` +3. In Visual Studio Code, follow these steps: + + 1. Open **Command Palette**. + 2. Run **MCP: List Servers**. + 3. Select **mendixMCP**. + 4. Start or restart the server. + 5. Accept the trust prompt if needed. + +4. Verify the setup by entering the following in the Visual Studio Code Copilot chat: + + 1. `Show my recent plans` + 2. `Show details for plan UUID ` + +##### Automatically Starting the Copilot MCP + +You can optionally choose to automatically start configured MCP servers for Visual Studio Code Copilot chat. To do that, add the following setting to the settings file (found at `C:/Users//AppData/Roaming/Code/User/settings.json`): + +```json +"chat.mcp.autostart": true +``` + +If the server is not automatically started, reload or restart Visual Studio Code. + +If you do not set the automatic start option, you can still start servers using **MCP: List Servers**. + #### Configuring Other MCP Clients For other MCP clients, refer to the client documentation for instructions on adding external MCP servers and configuring authentication. Most MCP clients support environment variable-based authentication, which is the recommended approach. diff --git a/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md new file mode 100644 index 00000000000..7f37d591550 --- /dev/null +++ b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md @@ -0,0 +1,27 @@ +--- +title: "Troubleshooting Maia Plan as MCP Server" +linktitle: "Troubleshooting" +url: /developerportal/maia-plan-mcp-troubleshooting/ +description: "Describes how to fix potential Maia Plan as an MCP server issues." +weight: 10 +--- + +## Introduction + +If you encounter issues with Maia Plan as MCP Server, use the following troubleshooting tips to solve them. + +## 401 or 403 Errors + +Your PAT is invalid or expired. Regenerate the token in [User Settings](/portal/user-settings/#pat) and update the `MENDIX_TOKEN` environment variable. + +## Tools Do Not Appear in Copilot + +Confirm that `mcp.json` is in the correct location (see [Configuring Visual Studio Code Copilot](#configuring-visual-studio-code-copilot)), then open **Command Palette** and run **MCP: Reset Cached Tools**. + +## Server Does Not Start + +Open **Command Palette**, run **MCP: Reset Trust**, then trust the server again when prompted. + +## Environment Variable Not Detected + +Fully restart Visual Studio Code after setting the `MENDIX_TOKEN` environment variable. A reload is not sufficient. From 09406c5f8371e6bb0db102e5ae08575f98646107 Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Fri, 10 Jul 2026 14:16:30 +0200 Subject: [PATCH 2/2] Add anchor --- .../docs/developerportal/maia-plan/maia-plan-mcp/_index.md | 2 +- .../maia-plan/maia-plan-mcp/troubleshooting.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md index c4e0d9f7d09..28083b5f56b 100644 --- a/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md +++ b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/_index.md @@ -104,7 +104,7 @@ To configure Claude Code to connect to the Maia Plan MCP Server, follow these st For detailed instructions, refer to the [Claude Code documentation](https://claude.com/docs/connectors/building/mcp). -#### Configuring Visual Studio Code Copilot +#### Configuring Visual Studio Code Copilot {#configuring-visual-studio-code-copilot} To configure Visual Studio Code Copilot to connect to the Maia Plan MCP server, follow these steps: diff --git a/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md index 7f37d591550..0c07560dc7e 100644 --- a/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md +++ b/content/en/docs/developerportal/maia-plan/maia-plan-mcp/troubleshooting.md @@ -12,11 +12,13 @@ If you encounter issues with Maia Plan as MCP Server, use the following troubles ## 401 or 403 Errors -Your PAT is invalid or expired. Regenerate the token in [User Settings](/portal/user-settings/#pat) and update the `MENDIX_TOKEN` environment variable. +Your personal access tokem (PAT) is invalid or expired. Regenerate the PAT in [User Settings](/portal/user-settings/#pat), then update the `MENDIX_TOKEN` environment variable. ## Tools Do Not Appear in Copilot -Confirm that `mcp.json` is in the correct location (see [Configuring Visual Studio Code Copilot](#configuring-visual-studio-code-copilot)), then open **Command Palette** and run **MCP: Reset Cached Tools**. +Confirm that `mcp.json` is in the correct location, then open **Command Palette** and run **MCP: Reset Cached Tools**. + +Refer to [Configuring Visual Studio Code Copilot](/developerportal/maia-plan-mcp/#configuring-visual-studio-code-copilot) for details. ## Server Does Not Start