MCP Server

An MCP Server lets you expose Sitevision functionality to external MCP clients in a structured way. Instead of building a custom integration for every use case, you can describe what your app provides as tools, resources, prompts and resource templates, and let MCP-compatible clients interact with it through a standard JSON-RPC interface.

You can use an MCP Server to expose Sitevision data, app configuration and server-side logic to AI assistants, developer tools and other MCP clients. A tool can perform an action or return computed output, a resource can expose readable data or documentation, and a prompt can generate reusable prompt content.

From a Sitevision perspective, an MCP Server is managed by an McpServerCustomModule. In that sense it is similar to how a RESTApp is managed by a HeadlessCustomModule. The custom module controls the endpoint, access rules and runtime configuration, while the executable code registers the MCP capabilities that should be exposed.

Responsibility split

Sitevision handles the MCP protocol implementation, endpoint routing and request processing. As a developer, you do not need to implement the JSON-RPC protocol layer yourself.

Your responsibility is to register the capabilities you want to expose, such as tools, resources, prompts and resource templates, and to provide the handlers that return the result.

Implementation details

MCP Servers are registration-based. Capabilities are registered through the mcpServer API, and Sitevision makes them available through the MCP server endpoint.

Tools and prompts use JSON Schema External link. to describe their input. Sitevision exposes the schema to MCP clients and validates incoming arguments before the handler is executed.

The current implementation supports stateless JSON-RPC over HTTP POST and does not support MCP-Session-Id, SSE, batch requests or inbound JSON-RPC response objects.

Build an MCP Server

Use the mcpServer API to register the capabilities you want to expose, such as tools, resources, prompts and resource templates.

You can register multiple capabilities on the same MCP Server, depending on what you want to expose.

The MCP Server is exposed through the module endpoint:

MCP Server endpoint

/mcp-api/{mcp-server-custom-module-name}

Register a tool

Use a tool when the client should perform an action or return computed output. Tool handlers return an object with a content array.

registerTool

import mcp from "@sitevision/api/server/mcpServer";
import privileged from "@sitevision/api/server/privileged";
import { getSemanticSearchHits } from "./util/semanticSearchUtil";
import { isPageFilter } from "./util/filters";

mcp.registerTool(
  "sitevision.docs.search",
  {
    description: `Semantic search in the official Sitevision developer documentation.
Returns relevant snippets and page resources.`,
    inputSchema: {
      type: "object",
      additionalProperties: false,
      required: ["query"],
      properties: {
        query: {
          type: "string",
          description: "Search query for the documentation."
        }
      }
    }
  },
  ({ query }) => {
    let results = [];

    privileged.doPrivilegedAction(() => {
      const hits = getSemanticSearchHits(query);

      results = hits.filter(isPageFilter).map((hit) => {
        return {
          score: hit.score,
          snippet: hit.text,
          page: {
            id: hit.id,
            uri: `sitevision://docs.sitevision/pages/${hit.id}`
          }
        };
      });
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2)
        }
      ]
    };
  }
);

Tools and prompts use JSON Schema to describe their input. Sitevision exposes the schema to MCP clients and validates incoming arguments before the handler is executed.

Register a resource template

Use a resource template when the content should be resolved dynamically from URI variables. Resource and resource template handlers return an object with a contents array.

registerResourceTemplate

import mcp from "@sitevision/api/server/mcpServer";
import resourceLocatorUtil from "@sitevision/api/server/ResourceLocatorUtil";
import { getPageAsMarkdown } from "./util/pageContentUtil";

mcp.registerResourceTemplate(
  "sitevision.docs.page",
  "sitevision://docs.sitevision/pages/{id}",
  {
    title: "Sitevision Documentation Page",
    description: `Full page from the official Sitevision developer documentation,
rendered as Markdown.`,
    mimeType: "text/markdown"
  },
  ({ uri, uriVariables }) => {
    const pageNode = resourceLocatorUtil.getNodeByIdentifier(uriVariables.id);
    const pageAsMarkdown = getPageAsMarkdown(pageNode);

    return {
      contents: [
        {
          uri,
          mimeType: "text/markdown",
          text: pageAsMarkdown
        }
      ]
    };
  }
);

Register a resource

Use a resource when the client should read fixed content. Resource handlers return an object with a contents array.

registerResource

import mcp from "@sitevision/api/server/mcpServer";

mcp.registerResource(
  "sitevision.docs.index",
  "sitevision://docs.sitevision/index",
  {
    title: "Sitevision documentation index",
    mimeType: "text/plain"
  },
  () => {
    return {
      contents: [
        {
          uri: "sitevision://docs.sitevision/index",
          mimeType: "text/plain",
          text: "Sitevision documentation index"
        }
      ]
    };
  }
);

Register a prompt

Use a prompt when the client should receive a prepared prompt or message structure. Prompt handlers return an object with a messages array.

registerPrompt

import mcp from "@sitevision/api/server/mcpServer";

mcp.registerPrompt(
  "sitevision.docs.answer",
  {
    title: "Sitevision documentation answer",
    description: "Create a prompt for answering questions about Sitevision.",
    inputSchema: {
      type: "object",
      additionalProperties: false,
      required: ["question"],
      properties: {
        question: {
          type: "string",
          description: "Question to answer."
        }
      }
    }
  },
  ({ question }) => {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Answer this question about Sitevision:\n\n${question}`
          }
        }
      ]
    };
  }
);

Notes

Use tools for actions and computed results.
Use resources for readable content.
Use prompts for AI-ready prompt/message structures.
Use resource templates when content depends on URI variables.
Handlers must be functions.
Names and URIs must be unique within the MCP Server.
Access to the endpoint is controlled by the module's API settings and POST permissions.

Available server-side APIs

An MCP Server can use the following server-side APIs (as well as the regular Sitevision Public API):

Useful resources

Model Context Protocol External link. for the protocol overview and specification
MCP Inspector External link. for debugging and testing MCP servers locally

Did you find the content on this page useful?