Integrating Custom MCP Tools with the Sitevision Assistant Module
This recipe guides you through creating and deploying an MCPServer Tool and integrating it with the Sitevision Assistant module External link..
By following the steps in this guide, you will build a simple MCPServer External link. which fetches real time data from an external source to enable the Assistant to answer more questions. The recipe covers the complete workflow. Creating the MCPServer External link., adding it to the Assistant and testing a few queries.
The goal of this recipe is to create a basic integration to test the workflow which should enable you to create more advanced solutions tailored to your organisations needs down the line.
Try to build the solution yourself when reading through the cookbook recipe. The complete MCPServer is available on github External link. if you get stuck.
Level: Intermediate
Estimated time: 60 min
Outcome: A working MCP Tool integrated with the Sitevision Assistant module
Id: recipe-002-custom-mcp-tool-assistant-integration
Version: 1.0
Prerequisites:
- Access to a Sitevision Enviroment
- Understanding of how to build and deploy apps in Sitevision
- Development environment configured.
- Permission to add and install modules on web site.
- Access to AI, Assistants and MCP
- Sitevision 2026.05.1
- Sitevision Assistant Module 2.6.6 (recommended 2.7.0)
Introduction Assistant
The Sitevision Assistant module External link. have been available since around Sitevision 2025.07.1. The Assistant allows you to define a database of knowledge which will be available to the AI. This way making it possible for you to tailor the Assistant to your organisation or use case. If you are unfamiliar here is one example query.
Why integrate custom tools?
As of writing, the Assistant includes one tool which collects information from the provided knowledge base and returns the relevant sources. In a knowledge base you can include pages and files from your website. It is also possible to add external sources to the knowledge base.
However this might not be enough for your use case. Maybe you want an AI that specializes in your organization's people and expertise, needs to retrieve real-time data from external sources, or can notify someone based on a user's query.
All of this should be possible with a custom MCPServer Tool integration.
Let us begin!
Building an MCPServer
Deploying the MCPServer
Start with creating an initial MCPServer External link. utilizing the create-sitevision-app-script.
Select the MCPServer alternative. Example snippets is made with TypeScript, this option is recommended. For addon you can set assistant-mcp-tool-cookbook.
Update the manifest.json with values you see fit. For example:
As per usual when working with Sitevision apps. Create an addon with npm run create-addon, then build and deploy the MCPServer with npm run dev.
If you check the Addon-tab in Sitevision you should see your newly deployed MCPServer.
Note: your view might look a little bit different. Image displays some UI updates coming in 2026.07.1
Creating an Assistant with the MCP Server
To get the initial integration up and running, we need to do some basic setup in the site settings. For this exercise we assume credentials for AI and Knowledge is already set, if you need this configured check in with your admin.
First create a Knowledge Base if you do not already have one (Site Settings / Knowledge). For this example we can simply create an empty one by not adding anything to scope and checking the external sources checkbox.
Then open the Assistants tab (Site Settings / Assistants) and add a new Assistant.
Select the AI, Knowledge base and your newly created MCP Server.
We can skip any custom instructions for this example.
As of writing a Knowledge base is always required, but starting from 2026.07.1 you are allowed to levave this empty if you supply at least one MCP Server instead.
If you have not already, download the Assistant module from Sitevision Marketplace External link., add it to a page (select the assistant we just created in the module configuration) and publish.
When a users ask a question the AI will now evaluate any tool registred by the MCP Server you supplied.
That's our setup done. Now let's focus on the intresting part, the actual tool.
A simple test tool call
Before we begin with the actual implementation. Let's try a quick test to check if everything works as expected.
If you check the index-file under the src-folder you should see an mcp tool registered, but let's change a few thing to create an easy testable tool. Replace the file content with:
A quick look at the building block of the tool.
Name
A tool requires a name, in this example we have called it example.echo. This is used by the AI to keep track of the tool.
Description
Maybe the most important thing is the description. The description is what is used to decide when your tools is supposed to be executed.
The description should explain what the tool is supposed to do and when. This is a super simple tool, and a simple description works. The more complex the solution, the more iterative work you have to put in to find the sweet spot.
In this example we instruct that the tool should be executed when the user queries "echo".
Callback
When the tool executes, the defined function runs. In this example we simply return a text, but in this callback you have access to the full Sitevision API, possibilities are close to endless. Returning some sort of text is advisable, even in cases where it's not the main goal, to give the AI some context to work with when generating an answer.
Deploy and test
If you got the dev-script running, save the file with the changes and it should immediatly force-deploy the application.
Try to ask the assistant "echo", you should expect an output similar to:
It is AI after all, so expect some variations, but if it's for off maybe something is wrong. A simple way to check during development is to add a log point in the callback. Run a query and check if the tool executes in the server log. Hopefully we did non run into any issues though!
When a tool should be executed is decided by the AI. The description is our way to instrcut the AI of how and when. Do note, this decision is not deterministic and may vary even for the exact repeating query.
If you encounter any issues with some queries, retry them a few times to figure out if this might be the issue. If the failing scenario is important, some specific targeted instructions might be of use to enforce the behavior.
Introduction for the external integration
Cool, we managed to integrate a custom tool with the Assistant. It is however a pretty useless addition. Still, we got a grasp of the core mechanics so let us create something more useful.
It is possible to post external non sitevision data to a knowledge base, however you would need to keep this up to date. In this example we will instead attempt to connect our external data through a Tool exposed through an MCP Server. This way we open up the possibility to fetch real time data directly from the external source.
Example use case for this exercise
For this cookbook recipe we have created a supporting RESTApp which we have deployed to developer.sitevision.se. If you are intrested we have included the source code for this RESTApp on github External link., but it is not necessary to view or understand this. You simply have to call the endpoint with the expected parameters.
The supporting RESTApp executes a search query on the site based on the parameters you provide. Familiarize yourself with the expected input and output before proceeding.
Expected RESTApp input:
| Property | Type | Description |
|---|---|---|
type | string | Defining what type of content should be searched. Expected input is "releaseNotes", "news" or "any". (mandatory) |
| latest | boolean | A boolean indicating if the seach should fetch the newly published sources or not (mandatory) |
| count | number | The maximum number of search hits (mandatory) |
| query | string | A keyword based search query. If latest == true this will be omitted. If false, provide a query to be able to find related sources. |
Expected example RESTApp output:
To summarize: we define which type of data we want, if new items should be prioritized, how many, and a potential search query.
In return we expect to get the source as markdown among with some information about the source.
Defining the tool use case
Finally we can start building the tool. We are going to call the RESTApp which fetches information from developer.sitevision.se. For this example we are going to instruct the AI that this tool should be executed when the user asks any developer related queries, and have it analyze the query to gather the correct parameters for the RESTApp endpoint.
Name and description
Replace the echo tool we created earlier with:
Initally we start with naming the tool. Try to make it descriptive, we use sitevision.developerDocumentation. For description we try to be as clear as possible to steer the AI into the tool as clearly as possible. We gave it a clear use case, defined its resposibilites and gave it some examples to easier understand which types of questions should be directed to the tool.
Writing a good description can seem like quite a daunting task. The simplest way to create descriptions is to describe your use case to your LLM of choice, to get a base template to work with. Then improve on this description through an iterative testing process. Find out what works and what does not, until you find a solution that work for your use case and covers some edge cases.
Properties
With the name and description in place continue with defining the parameters we want. Based on the description the AI will evaluate and generate these parameters which will be available in the tool execution step according to the user query, custom prompting and previous messages and responses in the conversation. You define these in the properties object in the inputSchema.
Properties are defined by a standardized JSON Schema. At the minimum you should provide type and description for each property. In this tool we will be utilizing four different properties. Make sure to read through each description in full to better understand the context. Below are some additional descriptions.
type
For the type we want to define which type of information we want to fetch. The RESTApp make it possible to specifically ask for releaseNotes or news. Other developer related queries should be directed to the any type. Describe in the description when each of these values should be selected. We also clearly defined the available options with an enum-definition.
latest
When user ask for something like "Show me the latest release notes" we want to ensure the search results are sorted accordingly. If query is not time related it should be false.
query
Since the RESTApp uses a keyword based search and not a semantic one, we want to extract the keywords from the user query to ensure good coverage.
strictQuery
The query might at times provide a few to many keywords. strictQuery will be used as a fallback query if the first one returns no results.
Tool execution
All of the properties are defined. We should expect our tool to be executed when a user ask a development related question in the assistant and provide us with the defined properies. Next step is to define what actually gets executed.
The tool is executed in a server side Sitevision enviroment, meaning you got access to the full Sitevision API whether it is collecting or manipulation data.
Replace the function with:
Collect the parameters we defined earlier. These we will send to a fetch function where we will execute the external seach.
If both searches provide no result, send an empty default state.
Simply keep the return text for the successfull search for now.
fetchItems
In a separate file create and export the fetch function (and import it in the tool file to access it). Use the url in the example to target the RESTApp.
An external request will be made to this domain, with the parameters we generated with the tool call. The count we simply set to 5 for this recipe.
Return the Array result on a successful call, if it fails an empty Array will be returned.
mapContent
One last step until we can see the actual responses in the assistant. We need to extract the text content. First adjust the return content.
Then we map the text content to a string. This will be the data the AI have access to when generating a response. Remember the expected response?
Simply grab the text content and separate with some new lines.
Testing the integration
Moment of truth right? Make sure you got all the changes deployed, and let's test the application. Here's a few examples with some expected output, variations may of course occur. Depending on when you attempt this recipe different source will be accessible. However if these queries do not work for you, you might have some bugs to locate and squash!
First try to ask for release notes. The type property will evaluate to releaseNotes and the latest property will be true. As of writing, 2026.05.1 is the latest release.
If we ask for news. The type property will evalutate to news. latest will likely evaluate to true, but your wording might make a difference. Either case, the results will be limited to the news archive on developer.sitevision.se.
If a specific development question is asked type will evaluate to any and a general search is executed. query in this example is likely something like "send event", "client event" or similiar.
Did it work? Hopefully it did! You can try a few different queries and see if you can get some expected results, and maybe play a bit with the descriptions to test it out.
In this example, we stayed entirely within the Sitevision ecosystem by executing a tool on one Sitevision website and calling a RESTApp on another. However, nothing prevents you from integrating with external systems such as SharePoint, Salesforce, or any other service. You simply need to handle and transform the response into a format that the assistant can work with.
Include a source list
If you have used the Sitevision Assistant before you might have noticed the included source list. If you create an Assistant which uses both the Knowledge Base setup in Sitevision and some external tools as well you run into the potential issue that some answer get a source list and some do not.
To give the answers generated from custom tool calls some extra credibility, consider providing some sources by following the defined syntax. In the tool return we can include souces, which the Assistant will pick up. For more information about this syntax consult the Custom Assistant Tool Documentation.
Displaying sources provided by your custom tool requires version 2.7.0. of the Assistant module.
In the return statement add an Array of sources by the path _meta.sitevision.assistant.sources. _meta is used to define metadata about the tool call results, but will not be included in data provided to the AI. It is simply an UI addition.
We made the response from the RESTApp very convenient. For other sources you might need to put in a little bit more effort to map it correctly.
With the type property we indicate that the source is external (i.e. it is not a sitevision node in the current environment). Sources will be added to the source list below the response.
Wrapping up
In this cookbook recipe we have explored how you can create and deploy an MCPServer in Sitevision. The MCPServer use case we have tried was to register a tool which fetches information from an external source and exposing this data to the Sitevision Assistant module.
This is just a basic example collecting some search based results. However since full API access is available in tools, you have nearly endless possibilites for how you apply the custom tools you create.
Also in this example we built one simple tools, an Assistant however can utilize multiple tools. It just demands a bit more of you as a developer to describe your tools as clearly as possible.
Start experimenting with your own custom tools, everything mentioned in this cookbook recipe is available to use.