SE
OfficialSearch

SearchUnify MCP Server for Cognitive Search Integration

Enable secure, seamless integration with SearchUnify MCP server to connect Cognitive Search to AI assistants like Claude Desktop, Cursor, and other MCP clients.

View on GitHub
Quick Install
npx -y @searchunify/su-mcp

Overview

SearchUnify MCP Server is a lightweight middleware that implements the Model Context Protocol (MCP) to expose SearchUnify Cognitive Search and analytics as MCP tools. It lets MCP-capable AI assistants (for example Claude Desktop, Cursor, or other clients) call enterprise search and analytics operations as if they were native tools, enabling context-aware retrieval, facet filtering, and analytics reporting inside LLM-driven workflows.

This server acts as a bridge between SearchUnify and external LLM environments. It uses the SearchUnify SDK to authenticate to your tenant, perform searches, fetch facet options, and retrieve various analytics reports. The server supports secure enterprise authentication, can run over stdio for local desktop assistants or HTTP for remote clients, and is intended for quick deployment via Docker or Node.js.

Features

  • LLM-integrated enterprise search with enriched GPT context when available
  • Faceted filtering (discover and apply facets such as index, category, source)
  • Analytics reports (zero-result queries, conversion data, session details, and more)
  • Multiple authentication methods: API key, OAuth2 password grant, or client credentials
  • Dual transport: stdio (local) and streamable HTTP (remote/cloud); run both concurrently
  • Simple deployment via Docker or Node.js

Prerequisites

  • Active SearchUnify tenant with:
    • Instance URL
    • Authentication credentials (API key or OAuth client)
    • A Search Client UID (for scoped queries)
  • Node.js (if running locally) or Docker (for containerized deployment)
  • MCP-compatible client (Claude Desktop, Cursor, etc.) for consuming tools

Installation / Configuration

Clone the repository and install dependencies:

git clone https://github.com/searchunify/su-mcp.git
cd su-mcp
npm install

Create an environment file (.env) with your tenant and server configuration. The exact variable names may vary slightly in the project; check the repository README for the canonical list. Typical variables include:

# SearchUnify tenant
SU_INSTANCE_URL=https://your-tenant.searchunify.com
SU_API_KEY=your_api_key_here
SU_CLIENT_UID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Server transport options
MCP_STDIO=true        # enable stdio transport (for local desktop assistants)
MCP_HTTP=true         # enable HTTP transport
PORT=8080             # HTTP port if MCP_HTTP=true

Run locally with Node:

# start the MCP server
npm start

Run with Docker (example):

docker build -t su-mcp .
docker run -e SU_INSTANCE_URL=... -e SU_API_KEY=... -e MCP_STDIO=true -p 8080:8080 su-mcp

Or use docker-compose (basic example):

version: '3.8'
services:
  su-mcp:
    image: your-registry/su-mcp:latest
    environment:
      - SU_INSTANCE_URL=https://your-tenant.searchunify.com
      - SU_API_KEY=your_api_key_here
      - SU_CLIENT_UID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - MCP_STDIO=true
      - MCP_HTTP=true
    ports:
      - "8080:8080"

Available Tools

The MCP server exposes four primary tools that LLMs can invoke.

  1. search
  • Purpose: run a SearchUnify query and return ordered results.
  • Parameters:
    • searchString (string, required): query text (3–100 chars)
    • aggregations (array, optional): list of facet filters; items { type, filter }
    • page (int, optional): page number (default 1)
    • pageSize (int, optional): results per page (default 10)
    • sortBy (string, optional): _score or post_time
    • versionResults (boolean, optional): enable versioning (default false)
  • Behavior: returns either enriched GPT-aware context (if tenant GPT features enabled) or standard hits (title, summary, URL). HTML is stripped from result snippets.
  1. get-filter-options
  • Purpose: discover available facets/filters for a given query (use before search to present selectable filters).
  • Parameters:
    • searchString (string, required)
    • aggregations (array, optional): currently applied filters to obtain contextual options
  • Returns: an array of aggregation groups. Each group has key, label, order, and values (value, displayName, contentName).
  1. analytics
  • Purpose: retrieve SearchUnify analytics reports.
  • Parameters:
    • reportType (string, required): enum identifying report (examples below)
    • startDate (string, required): report start date (ISO)
    • endDate (string, required): report end date (ISO)
    • count (number, required): number of records to retrieve
  • Example reportType values:
    • searchQueryWithNoClicks
    • searchQueryWithResult
    • searchQueryWithoutResults
    • getAllSearchQuery
    • getAllSearchConversion
    • averageClickPosition
    • sessionDetails
  1. get-search-clients
  • Purpose: list search clients configured in the tenant (ID, name, UID, type).
  • Parameters: none (tenant derived from auth credentials)

Example Requests

search example payload (JSON):

{
  "searchString": "installation error 502",
  "aggregations": [{"type":"_index","filter":"docs"}],
  "page": 1,
  "pageSize": 5,
  "sortBy": "_score"
}

get-filter-options example:

{
  "searchString": "cloud storage",
  "aggregations": []
}

analytics example:

{
  "reportType": "searchQueryWithoutResults",
  "startDate": "2026-03-01",
  "endDate": "2026-03-31",
  "count": 50
}

Use Cases

  • Claude Desktop: run the MCP server in stdio mode and register it as a tool — the assistant can fetch context-aware SearchUnify content inline while drafting answers.
  • Remote LLM/agent: enable HTTP transport so cloud-hosted agents or orchestration systems can call search and analytics endpoints programmatically.
  • Customer support augmentation: use search with facet filters to surface relevant KB articles and present explainable links in agent workflows.
  • Search tuning and diagnostics: fetch searchQueryWithoutResults and averageClickPosition reports to identify gaps in indexed content or ranking issues.
  • Guided discovery: call get-filter-options before search to present dynamic filter choices in an LLM-driven UI.
  • GitHub: https://github.com/searchunify/su-mcp/
  • Model Context Protocol: https://modelcontextprotocol.io/
  • SearchUnify documentation and SDK: check your tenant docs or the su-sdk-js package for authentication details

For deployment specifics (exact environment variable names, advanced auth flows, and sample client integrations), refer to the repository README and the included examples.

Tags:search