MCP Integration

The QSC Search MCP Server exposes your QSC Search API as a tool via the Model Context Protocol (MCP). This allows MCP-compatible AI clients — such as Claude Desktop, Cursor, or the QSC Agent — to search your index directly.

AI Client  ──MCP──▶  QSC Search MCP Server  ──HTTP──▶  QSC Search API
                       (Python / FastMCP)                (Spring Boot)

---

Prerequisites

• A configured and running QSC Search App
• The QSC Search MCP Server deployed and accessible (see Deployment)

Enable MCP for a Search App

MCP is enabled per search app through the Variables configuration.

1. Go to Quasiris Search Cloud
2. Open your Search App configuration
3. Go to the Variables tab
4. Add a new variable with key mcp and a JSON object as value:

{
  "enabled": true,
  "description": "Search for products in the catalog",
  "tags": ["search", "products"],
  "baseRequest": {
    "rows": 10,
    "page": 1
  }
}

5. Click Save

Configuration Fields

Field	Type	Required	Description
enabled	boolean	Yes	Set to true to enable MCP for this search app
description	string	No	Description of the search tool shown to AI assistants
tags	string[]	No	Tags for the search tool (e.g. ["search", "products"])
baseRequest	object	No	Default request parameters merged with the tool input. Tool input takes precedence

How baseRequest works

The baseRequest defines default parameters that are sent with every search. When the AI assistant provides parameters, they are merged on top of the base request.

For example, with this baseRequest:

{
  "rows": 10,
  "page": 1
}

If the AI sends {"q": "shoes", "rows": 5}, the final request becomes:

{
  "rows": 5,
  "page": 1,
  "q": "shoes"
}

---

MCP Endpoint

URL: https://qsc.quasiris.de/api/v1/mcp/{tenant}/{code}

Example: https://qsc.quasiris.de/api/v1/mcp/demo/trendware

Protocol: MCP over Streamable HTTP (stateless)

Headers

If the search endpoint has security enabled you must add these headers

Header	Required	Description
x-qsc-token	Conditional	API token for authentication
authorization	Conditional	Bearer token for OAuth-based authentication

Either x-qsc-token or authorization must be provided.

---

MCP Tool: search

The MCP server exposes a single search tool with the following parameters:

Parameter	Type	Required	Description
q	string	No	Search query. Uses Elasticsearch query syntax. * matches all
page	int	No	Page number (minimum value is 1)
rows	int	No	Number of result documents to return
locale	string	No	Locale in nn-NN format (e.g. de-DE). Default is null

The tool returns the full QSC Search response including documents, facets, and paging information.

---

Authentication Flow

The MCP server enforces authentication before making the search tool available:

1. The AI client connects to /api/v1/mcp/{tenant}/{code} with an auth credential (x-qsc-token or authorization header).
2. The MCP server resolves the search app configuration from the QSC Admin API.
3. It checks if MCP is enabled for the search app (the mcp variable must exist with enabled: true).
4. It makes a probe request to the QSC Search API with the client's auth credentials.
5. If the probe does not return 401 or 403, the search tool is made available to the AI client.
6. When the tool is invoked, the same auth credentials are forwarded to the actual search request.

If MCP is not enabled or authentication fails, no tools are returned to the AI client.

---

Connecting AI Clients

Claude Desktop / Cursor

Add the following to your MCP client configuration (replace {tenant} and {code} with your actual values):

{
  "mcpServers": {
    "qsc-search": {
      "url": "https://qsc.quasiris.de/api/v1/mcp/{tenant}/{code}",
      "headers": {
        "x-qsc-token": "<your-token>"
      }
    }
  }
}

Example for tenant demo and search app trendware:

{
  "mcpServers": {
    "qsc-search": {
      "url": "https://qsc.quasiris.de/api/v1/mcp/demo/trendware",
      "headers": {
        "x-qsc-token": "<your-token>"
      }
    }
  }
}

QSC Agent

The MCP server can be used as a tool server for the QSC Agent. Add it to the agent configuration:

{
  "mcp_servers": [
    {
      "url": "https://qsc.quasiris.de/api/v1/mcp/{tenant}/{code}",
      "label": "product_search"
    }
  ]
}

The agent will forward the appropriate authentication headers automatically.