Skip to main content

Set up the Halo MCP server

Halo's MCP server gives AI agents access to ticket management, knowledge base search, asset lookup, and runbook execution across HaloPSA, HaloITSM, and HaloCRM. This guide covers enabling the MCP endpoint in Halo, registering an OAuth application, and connecting your instance to MintMCP.

Prerequisites​

  • A MintMCP admin account
  • Halo v2.236 or later with the AI module enabled
  • Access to Halo's Configuration settings

Enable the MCP endpoint in Halo​

  1. In Halo, go to Configuration > AI.
  2. Verify that a Default AI Connection is configured. Halo's built-in connection is available if you haven't set up your own.
  3. Check Enable the MCP Endpoint.

The page shows your MCP endpoint URL in the format https://[YOURHALOURL]/api/mcp. Copy it before moving to the next section.

Register an OAuth application​

  1. Go to Configuration > Integrations > Halo API > View Applications.

    Halo API Applications section with the View Applications button

  2. Create a new application by clicking + New.

    Applications toolbar with the New button

  3. Set Authentication Method to Authorisation Code (Native Application).

    Authentication Method options with Authorisation Code (Native Application) selected

  4. Enable Use a client secret for the token request.

    Client Secret set to Use a client secret for the token request, with the Generate button

  5. In Login Redirect URLs, add https://app.mintmcp.com/oauth/callback.

  6. In Logout Redirect URLs, add the same URL: https://app.mintmcp.com/oauth/callback.

    Login Redirect URL and Logout Redirect URL fields both set to https://app.mintmcp.com/oauth/callback

  7. Open the Permissions tab and set the scope to all:standard.

    Permissions tab with the all:standard scope checked

  8. Open the Security tab and add app.mintmcp.com to the CORS Whitelist.

    Security tab with app.mintmcp.com added to the CORS Whitelist

  9. Save the application.

  10. Copy the Client ID shown on the application details page.

    Application Details tab showing the Client ID field

  11. To create a Client Secret, click Edit, then under Client Secret click Generate. Copy the secret immediately, since it is only shown once.

    Client Secret set to Use a client secret for the token request, with the Generate button

Add Halo to MintMCP​

  1. In MintMCP, go to MCP store and open the Recommended servers tab.
  2. Select Halo to open the Configure Halo panel.
  3. In Server URL, enter your Halo MCP endpoint: https://[YOURHALOURL]/api/mcp, replacing [YOURHALOURL] with your Halo instance domain (for example, yourcompany.halopsa.com).
  4. Confirm Connection type is set to Per-user credentials.
  5. Confirm Authorization method is set to OAuth.
  6. Open OAuth Client Advanced Settings and paste the Client ID and Client Secret from the previous step.
  7. Click Install.

Security considerations​

  • The Client Secret is displayed only once. Copy it before closing the application page and store it securely.
  • Scope is fixed to all:standard in Halo, so there are no additional scopes to configure in MintMCP.
  • Each user authenticates with their own Halo identity, so actions are attributed to individual users rather than a shared account.
  • Restrict the CORS Whitelist to app.mintmcp.com only, and remove the default Claude entries if they were pre-filled.

Troubleshooting​

  • AI module or MCP endpoint option not visible: the AI module must be enabled by a Halo administrator before the MCP endpoint setting appears. Refer to Halo's MCP documentation or contact Halo support.
  • "Enable the MCP Endpoint" is missing after the AI module is enabled: requires Halo v2.236 or later. Check your version with Halo support.
  • OAuth fails or the consent screen does not appear: confirm that both the Login and Logout Redirect URLs are set to https://app.mintmcp.com/oauth/callback in the Halo application settings, and that app.mintmcp.com is in the CORS Whitelist.
  • Client Secret unavailable: the secret is shown only once at generation. To get a fresh one, edit the application, then under Client Secret click Generate. This replaces the old secret, so update it in MintMCP.

Next steps​