<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><p><strong>In this gu</strong><strong>ide we will cover:</strong></p><p><strong>- What is the OpenAI MCP Server Connection?</strong></p><p><strong>- Enabling the Halo MCP Server</strong></p><p><strong>- Example Usage</strong></p><p><strong>- Adding Functions</strong></p><p><strong>- Tool Collections</strong></p><p data-pasted="true"><strong>- External MCP Server connections (v2.236+) </strong></p><p><br></p><p><br></p><p><strong>Related Guides:</strong></p><ul><li style="font-weight: bold;"><strong><a href="https://usehalo.com/haloitsm/guides/2726/" target="_blank" rel="noopener noreferrer" style="font-weight: bold;">MCP Endpoint: Use the Chatbot to Query and Update Data in your Instance</a></strong><p><br></p></li></ul><p><br></p><p><strong><span style="font-size: 14pt;">What is the OpenAI MCP Server Connection?</span></strong></p><p id="isPasted">The Model Context Protocol (MCP) HTTP endpoint allows AI assistants such as OpenAI to connect and dynamically invoke tools in the Halo API such as knowledge search, ticket logging and updating/executing runbooks. Essentially, using AI to trigger a function similar to virtual agents.</p><p><br></p><p>From v2.236+, tickets, actions, and Knowledge Base Articles created by a MCP Tool Collection will be "flagged" as AI in reporting under the columns: faicreated, aacreated, and kbaicreated. The ID of the MCP Tool Collection that was used to create the entity can also be identified using the following fields: fvirtualagentid, avirtualagentid, and kbvirtualagentid. This will correlate to the ID in the VirtualAgent table. </p><p><br></p><p><strong><span style="font-size: 14pt;">Enabling the Halo MCP Server</span></strong></p><p id="isPasted">Navigate to Configuration > AI and check the "Enable the MCP Endpoint" setting to enable the endpoint.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImUwYTgwMDczLTkwNTUtNDZkNy1hYWVlLWQzZWQ1OTE1YjUyMiJ9.CdEpxz3tXSqggStOFtvj7Xun1gkwbkn3ofcqQk6YFLg" class="fr-fic fr-fil fr-dib" width="1457" height="142"></p><p><strong><span style="font-size: 10pt;">Fig 1. Enabling the endpoint</span></strong></p><p><br></p><p><strong><span style="font-size: 11pt;"><em>Note: In order for the "Remote MCP Server" section to appear you need to have chosen a "Default AI Connection" for your instance. The Halo default connection can be used if you do not have your own. For information on connection types checkout our guide </em></span></strong><em><span style="font-size: 11pt;"><a href="https://usehalo.com/haloitsm/guides/2385" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;"><strong>here</strong></a><strong>. </strong></span></em></p><p><br></p><p><strong><span style="font-size: 14pt;">Example Usage</span></strong></p><p>Upon enabling, you will then see some information and a sample request for using Halo MCP within OpenAI. This will allow the conversational AI to invoke functions within your Halo API whenever it thinks it needs to use them.</p><p><br></p><p id="isPasted">In the example below, the AI will look at what functions are available in Halo. It will then discover functions for creating a new ticket and assigning it to the agent that the access token is for, and determine that it should use them and execute them one after the other, and respond to the user telling them the ID of their new ticket.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkwYjg5MDE5LWExNmItNDkyYi1iYzAxLWE5YjJmYjY5OWRiYyJ9.mCK_WW33VlH4b-Ffd0lKklazyV6N5cpOrway_rmAIe0" class="fr-fic fr-fil fr-dib" width="1220" style="width: 1222px; height: 295.023px;" height="295"></p><p><strong><span style="font-size: 10pt;">Fig 2. Example request</span></strong></p><p><br></p><p>If the program you are using to connect to the MCP endpoint does not accept any other method of OAuth flows, a static API Key can be used. Navigate to Configuration > Integrations > Halo API > View Applications, and create a new Application.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkxNGY1ZGE2LWIxYjEtNGMwOS1iOTIxLTlkN2ZlM2RiOGFlNiJ9.yYEzETrru-HII005iHuPV_OubKkLC9G_5dqnnnTiJjA" class="fr-fic fr-fil fr-dib" width="384" height="456"></p><p><strong><span style="font-size: 10pt;">Fig 3. Application Authentication options</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Adding Functions</span></strong></p><p id="isPasted">The tools/functions that are available in the MCP endpoint are as follows. By default, all system tools will be enabled for the MCP endpoint, but you can disable this and instead specify which functions/tools you would like to be available.</p><p><br></p><p>The available system tools are as follows:</p><ul><li><strong>Action a Ticket -</strong> Allows you to add any action that is configured to be a 'quick action' to a ticket on behalf of the agent, allowing agents to update tickets. </li><li><strong>Add Note to Ticket -</strong> Allows you to add a private note to a ticket on behalf of the agent, allowing agents to update tickets.</li><li><strong>Apply AI Suggestion - </strong>Applies AI suggestions to a ticket, rather than the agent having to do this from within a ticket. </li><li><strong>Assign to me -</strong> Re-assigns a ticket from one agent to the agent logged in.</li><li><strong>Get Assigned Tickets - </strong>Returns a list of tickets that are assigned to the agent. </li><li><strong>Search Knowledge Base -</strong> Searches the knowledge base based in the input from the agent. It can return resolution suggestions based on the relevant articles it finds, it can also suggest articles for the agent to read. </li><li><strong>Get matching Articles and Tickets for a Ticket -</strong> Re-runs AI ticket and article matching for a specific ticket. Beneficial when the ticket has been open for some time, in which closer matches may exist. This allows the agent to ensure the matched tickets and articles are the most up to date matches in the database. </li><li data-pasted="true"><strong>Get One Article -</strong> Can summarise or extract details from a specific KB article and return these to the agent. </li><li><strong>Get One Ticket -</strong> Return a list of tickets that are assigned to the agent. </li><li><strong>Get User Info -</strong> Returns the information held about the user in Halo. </li><li><strong>Search Service Catalogue -</strong> Search services using AI Search, and receive the names and links to any matched services, and direct the user to the relevant service where appropriate. </li><li><strong>Log Time - </strong>Logs a quick time entry for the agent.</li><li><strong>Search Tickets - </strong>Searches ticket content based on a prompt from the agent. Allowing it to effectively summarise and suggest replies or resolutions to tickets based on this info.</li><li data-pasted="true"><strong>Search Assets (v2.236+) -</strong> Searches assets based on a prompt from the agent.</li><li data-pasted="true"><strong>Get One Asset (v2.236+) - </strong>Can summarise or extract details from a specific assets and return these to the agent. </li><li><strong>Search Users (v2.236+) -</strong> Searches users based on a prompt from the agent. (Only available to agents)</li><li><strong>Get One User</strong><strong data-pasted="true"> (v2.236+)</strong> <span style="color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;" data-pasted="true"><strong>-</strong></span> Can summarise or extract details from a specific user and return these to the agent (only available to agents). </li><li><strong>Use specific action (v2.238+) -</strong>Can add an action to a ticket, including populating any fields on this action. The action must be available to use on the ticket's current workflow step, and the AI Agent must also have access to a function that allows it to check the workflow step of the ticket (such as get one ticket). When this function is being called by a user the action must be allowed to be used by users.<p><br></p></li></ul><p><br></p><p>To have all tools enabled for the endpoint ensure "Include all system tools" is enabled. Keep in mind if this is enabled any of the available tools will be able to be carried out using the endpoint, regardless of the agent's permissions. </p><p><br></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQwZDc2NjRkLWIxNTgtNDA0OC05NjBmLTAxODllMGNjZjFkZiJ9.XRsrreycbzUPm5nquWGnp746qFZ3VEXCnZocax_xpCI" class="fr-fic fr-fil fr-dib" width="498" height="326"></p><p><strong><span style="font-size: 10pt;">Fig 4. System tools</span></strong></p><p><br></p><p>If "Include all system tools" is disabled, you can choose which tools are available to use at the endpoint by adding the allowed tools into the 'Tools' table. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU3ZTFmMTAxLTg5YjEtNGEwZC04Y2EzLTU0NDRlMWM5ODlhNiJ9.ZoW5CYls7CB-ZaAgiivuwXYCVNrLZVnmf9JhSmacdBg" class="fr-fic fr-fil fr-dib" width="1219" style="width: 1221px; height: 135.203px;" height="135"></p><p><strong><span style="font-size: 10pt;">Fig 5. Tools table</span></strong></p><p><br></p><p>Custom tools can also be configured here to allow other functions to be carried out at the endpoint. </p><p><br></p><p>Custom Tools can be created with the following uses: </p><ul><li><strong>Use an AI Ability (v2.232+) -</strong> Allows you to use/trigger an AI ability. See our guide on AI Abilities for information on this.</li><li><strong>Log a ticket of a certain type or template -</strong> Logs a new ticket of a specified type or template. From v2.232+ you can also use the option "Any Ticket Type the user has access to" to allow users/agents to log any ticket type they have access to, provided they provide the ticket type name. From v2.238+, you can set the fields to use a as parameters. This allows you to choose between including the ticket type's field list as parameters for the AI to populate, or or using the Summary and Details. </li><li data-pasted="true"><strong>Get Report Data -</strong> Returns the data from a specified report. </li><li><strong>Execute a Runbook -</strong> Executes a runbook of choice.</li></ul><p><br></p><p>This increases the number of functions that can be carried out at the endpoint as well as the ease of executing these automations. Automations can be triggered based on user requests, leveraging AI to execute the correct automation based on the user's request. When adding a custom function you will need to give the function a name and give the AI model information/a prompt on when this function should be executed. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIzZjcwYTYwLWFkNzQtNDkxNC1hODQzLWRhZWNhMjRmZjc1OSJ9._ob-Hk5hkYCENij2Em02WBsUVLHslVTnK5dQyuGJf8w" class="fr-fic fr-fil fr-dib" width="541" style="width: 543px; height: 749.018px;" height="749"></p><p><strong><span style="font-size: 10pt;">Fig 6. Example Custom Function</span></strong></p><p><br></p><p>When a custom function to execute a runbook is set, the runbook must complete quickly in order to not timeout the HTTP request to the MCP endpoint. The option to "Fire and forget" is intended for longer running tasks where the AI does not need to return the runbook result. If using the "Execute and await completion" option, a warning will show to ensure the runbook can complete within 1 minute to avoid these timeouts.</p><p><br></p><p><strong><span style="font-size: 14pt;">Tool Collections (v2.232+)</span></strong></p><p>From v2.232+ tool collections can be created, these allow you to create additional MCP endpoints with a chosen set of functions. </p><p><br></p><p data-pasted="true">This allows you to have multiple MCP endpoints, each with a different set of allowed functions, based on what you would like agents/users to be able to do. For example, you could create a new endpoint that is only allowed to execute functions specific to users (e.g. logging new tickets, searching the knowledge base), this endpoint can then be used to integrate with another AI tool that users have access too. </p><p><br></p><p>Tool collections allow you to have different endpoints with different levels of access, such as an endpoint with user level tools, an endpoint with standard agent level tools and an endpoint with admin level tools. Therefore third-party AI systems can access different sets of tools based on the URL (endpoint) provided.</p><p><br></p><p><strong><span style="font-size: 12pt;">Creating Tool Collections</span></strong></p><p>To create a new tool collection head to Configuration > AI > MCP Tool Collections.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg4YzA0NTA1LTNjZmEtNGI2Ny1iOTFhLTUyNGJlMjIzMmJiNiJ9.Kmb1-p0yehl8JtJ1jyh5cd4tLnXpxVZc0DB7hEfNlW4" class="fr-fic fr-fil fr-dib" width="1856" style="width: 1858px; height: 946.938px;" height="947"></p><p><strong><span style="font-size: 10pt;">Fig 7. Create new MCP tool Collection</span></strong></p><p><br></p><p>When creating a tool collection, give it a name and choose whether the collection will be used by agents or users using the "Type" field. This will control the functions/tools that are available to be added to this collection. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJmZWZkNmU3LWMyZTMtNGQ3Ni05YzE4LTFmZDg3ZDJlNjViNSJ9.NMLLPLR8BopUTTx-93vLSB4_8MSd2zGX2rVpuMLg9T4" class="fr-fic fr-fil fr-dib" width="946" style="width: 948px; height: 426.477px;" height="426"></p><p><strong><span style="font-size: 10pt;">Fig 8. New MCP Tool Collection</span></strong></p><p><br></p><p>When 'User Functions' is chosen, only functions applicable to users will be able to be added to the collection. When 'Agent Functions' is chosen, only functions applicable to agents will be able to be added to the collection. </p><p><br></p><p>Available User Functions:</p><ul><li>Action a Ticket (User actions only) (v2.232+)</li><li>AI Ability (v2.232+)</li><li>Search Knowledge Base</li><li>Get My Tickets</li><li>Get One Article (v2.232+)</li><li>Get One Ticket (v2.232+)</li><li>Get Report Data</li><li>Get User Info</li><li>Log a Ticket</li><li>Search Service Catalogue</li><li>Execute a Runbook</li><li>Search Tickets</li><li>Update a Ticket</li><li>Use specific action (v2.238+) <p><br></p></li></ul><p><br></p><p>Available Agent Functions:</p><ul><li data-pasted="true">Action a Ticket </li><li>Apply AI Suggestion </li><li>Assign to me</li><li>Get Assigned Tickets</li><li>Search Knowledge Base</li><li>Get matching Articles and Tickets for a Ticket </li><li>Get One Article</li><li>Get One Ticket </li><li>Get User Info</li><li>Search Service Catalogue </li><li>Log Time</li><li>Search Tickets</li><li>Use specific action (v2.238+)</li></ul><p><br></p><p><strong><em>Note: When setting up the authorisation for the MCP endpoint, ensure the application used to generate the bearer token is granted only the permissions required by the available tools. For example, if the tool collection only exposes user-related functions, the application should be granted user-level permissions only</em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Set Which Functions are available for a Collection</span></strong></p><p>If you would like all system functions to be available for the collection enable "Include all system functions" for the collection. Otherwise, uncheck this and add the tools you would like to be available in the "Functions" table. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImVjY2JiNDk2LWQ5MzYtNGM4OS1iMjEwLTQ5MjIxZjhmMGE3OCJ9.EcUuBd_wx7SUkQ4xJI1OKLAaBlKJbaQTVtFIjQ6AfEQ" class="fr-fic fr-fil fr-dib" width="1593" style="width: 1595px; height: 665.727px;" height="666"></p><p><strong><span style="font-size: 10pt;">Fig 9. Functions for Tool Collection</span></strong></p><p><br></p><p><strong><em>Note: If you have set the type of the collection to be "User Functions" when all system functions are enabled only user system functions will be available. </em></strong></p><p><br></p><p>Tools are added/configured here in the same way as outlined in the "Adding Functions" section of this guide. </p><p><br></p><p>In the Figure 10 example we have created a new tool collection that will be used by users. Users can carry out any system functions as well as the custom function (CF_password_reset).</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhlOTU5ZTJiLWFmMzAtNDFlYy05N2Y2LWVjNDFhYTk0OTdlYiJ9.yB7vE9rVROzKIh7hAfU31P0tVO3C2xjkfAVCylU8R9A" class="fr-fic fr-fil fr-dib" width="1652" style="width: 1654px; height: 651.328px;" height="651"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 10. Example Functions for tool collection</span></strong></p><p><br></p><p>Once the tool collection is saved the server URL for this MCP endpoint will be provided. Along with an example JSON body that can be used to carry out the functions available at the MCP server using the OpenAI responses API. </p><p><br></p><p>This can then be used to build custom integrations with third party AI tools so that functions can be carried out in Halo from these tools.</p><p><br></p><p data-pasted="true"><span style="font-size: 14pt;"><strong>External MCP Server connections (v2.236+) </strong></span></p><p data-pasted="true">Configuring connections to third-party MCP servers allowd the AI to call external tools for other applications.</p><p>To set up your connection, head to Configuration > and add to the "External MCP Servers" table. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE5ODEwM2E5LWQ3OTgtNDEwNi04NzUzLWFhMWQ2ZDczOTVjZiJ9.bZyT2ghIgtLLZz8kb8H_Bdi2O_gX8KSjd0Fm2JtC6v4" class="fr-fic fr-fil fr-dib" width="1008" style="width: 1010px; height: 264.387px;" height="264"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 11. External MPC Servers </span></strong></p><p><br></p><p>Here you will need to set a a name, server URL, authorisation header, and the API key. Once saved, this MCP connection can be added to <a href="https://usehalo.com/haloitsm/guides/2336" target="_blank" rel="noopener noreferrer">Virtual Agents</a>, Operations Agents and <a href="https://usehalo.com/haloitsm/guides/2783/" target="_blank" rel="noopener noreferrer">AI Agents</a>. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU5NGM1NTU4LTM5ZGEtNGZmMS1iMDcwLThiODk0MDA3MWMwYSJ9.bG3NfJWUgi0MKziWIM6mkZJilDv97IvYZntyZnT2s6g" class="fr-fic fr-fil fr-dib" width="689" height="529"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 12. Connecting external</span></strong><strong><span style="font-size: 10pt;"> MCPs servers </span></strong></p>
