Document MCP preset servers and fixed OAuth callback port range

Author: retran

content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-mcp.md

@@ -26,6 +26,25 @@ There are two ways to open the MCP Client panel:
 * Click the **Configure MCP Connections** ({{% icon name="plug" %}}) icon under the **Maia Chat** tab.
 * Go to the **View** menu and click **MCP Settings**.
 
+### Preset Servers {#preset-servers}
+
+Preset MCP servers let you connect to common services without entering URLs or credentials.
+
+#### Mendix Marketplace {#mendix-marketplace-preset}
+
+Studio Pro adds the **Mendix Marketplace** connection automatically when you open the MCP Client panel. It authenticates with your Mendix ID — no extra credentials needed. Marketplace tools are disabled by default — enable the ones you need from the expanded card.
+
+Mendix manages this connection. You cannot remove it, but you can enable or disable it using the checkbox on the **Mendix Marketplace** card.
+
+#### Preset Catalog {#preset-catalog}
+
+Click **+ Add MCP Server** to open the catalog alongside the manual entry form. Each preset appears as a tile. Click a tile to select it — Studio Pro sets the URL, connection type, and authentication type automatically. Only the server name remains editable.
+
+* For OAuth presets: click **Authenticate** to authorize in your browser, then click **OK** to save.
+* For bearer token presets: enter your token, then click **OK**.
+
+Tools from new preset connections are **disabled by default**. Enable the tools you need from the expanded connection card.
+
 ### Adding an MCP Server {#adding-server}
 
 To add a server, click **+ Add MCP Server**, fill in the following fields, and click **OK**:
@@ -41,6 +60,7 @@ Choose how Studio Pro authenticates with the MCP server:
 
 * **No Auth** — select this for servers that do not require credentials.
 * **Bearer Token** — paste an API token or personal access token. The token is stored securely and is not exposed after entry.
+* **Mendix Identity** — authenticates using the Mendix account you are already signed in to Studio Pro with. No extra credentials are needed. Use this option when connecting to MCP services provided by Mendix.
 * **OAuth 2.1** — a browser window opens so you can authorize Studio Pro with the server's provider. Two optional fields appear:
     * **Client ID** — required if the server does not support automatic client registration.
     * **Client Secret** — required by some providers (for example, GitHub).
@@ -53,7 +73,7 @@ Most major providers — including GitHub and Figma — do not support automatic
 2. Fill in the following information:
     * **Application name** — for example, `Mendix Studio Pro`
     * **Homepage URL** — for example, `https://mendix.com`
-    * **Authorization callback URL** — `http://localhost:{port}/mcp/oauth/callback` (see the [Callback URL](#callback-url) section below)
+    * **Authorization callback URL** — `http://localhost:44380/mcp/oauth/callback` (GitHub allows only one; see [Callback URL](#callback-url))
 3. Click **Register application**, then copy the **Client ID**.
 4. Click **Generate a new client secret** and copy it — GitHub shows it only once.
 5. In Studio Pro, add a server with the following details:
@@ -68,10 +88,26 @@ For Figma MCP, the simplest option is to generate a personal access token in Fig
 
 ##### Callback URL {#callback-url}
 
-The OAuth callback URL format is `http://localhost:{port}/mcp/oauth/callback`. The port is assigned by Studio Pro's built-in web server. You can find the actual port within the callback URL that Studio Pro generates when you add the server.
+The OAuth callback URL format is `http://localhost:{port}/mcp/oauth/callback`. Studio Pro uses a fixed port from the range **44380–44384** — one port per running Studio Pro instance, starting from 44380.
+
+When registering an OAuth app with a provider, enter all five callback URLs if the provider allows multiple:
+
+* `http://localhost:44380/mcp/oauth/callback`
+* `http://localhost:44381/mcp/oauth/callback`
+* `http://localhost:44382/mcp/oauth/callback`
+* `http://localhost:44383/mcp/oauth/callback`
+* `http://localhost:44384/mcp/oauth/callback`
+
+If the provider allows only one callback URL, use `http://localhost:44380/mcp/oauth/callback` — Studio Pro always tries port 44380 first.
 
 {{% alert color="info" %}}
-If your OAuth app requires a fixed callback URL, you can start Studio Pro with the `--web-server-port=45678` command-line flag to use a specific port.
+If all ports in the range 44380–44384 are occupied (for example, when multiple Studio Pro instances are open), Studio Pro shows an error. Close another instance or free a port and try connecting again.
+{{% /alert %}}
+
+Use `--mcp-oauth-ports` to override the port range (for example, `--mcp-oauth-ports=44380-44384` or `--mcp-oauth-ports=44380,39321`).
+
+{{% alert color="warning" %}}
+For servers that validate the callback URL against the [OAuth Client ID Metadata Document (SEP-991)](https://modelcontextprotocol.io/seps/991-enable-url-based-client-registration-using-oauth-c), custom ports will always be rejected — the metadata document is hosted by Mendix and lists only ports 44380–44384 as valid callback URLs. Custom ports are only useful for servers that do not enforce this validation, such as internal or self-hosted servers.
 {{% /alert %}}
 
 ### Managing Connections {#managing-connections}
@@ -118,6 +154,7 @@ You see the answer from Maia, not the raw tool output.
 | "Token exchange failed" or "incorrect_client_credentials" | Verify your Client ID and Client Secret. Check that the callback URL matches. |
 | Authentication stuck in "Authenticating..." | Check that no firewall blocks localhost. Remove the server and add it again to restart the flow. |
 | Connection fails immediately | Verify the URL. Try switching between **HTTP (Streamable)** and **SSE (Legacy)**. |
+| "All OAuth callback ports are in use" | Close another Studio Pro instance to free a port in range 44380–44384, then try connecting again. |
 
 ## Limitations {#limitations}