SearchUnify MCP Tools and Response Formats

SearchUnify MCP exposes core tools for search, filtering, analytics, and search client discovery. The login tool is available only through the /mcp-connect endpoint.

Note: The login tool is available only through the /mcp-connect endpoint. It is not available on standard OAuth or header-based endpoints.

search

Use the search tool to run a SearchUnify query and retrieve relevant search results from the connected SearchUnify instance. The tool can return standard search results or enriched GPT context, depending on the configuration of the SearchUnify search client.

Supported parameters

Aggregation Object Schema

Use the following schema when passing filters to the aggregations parameter:

{
  "type": "_type",
  "filter": "document"
}

Example Request

{
 "searchString": "configure search client",
 "page": 1,
 "pageSize": 10,
 "sortBy": "_score",
 "versionResults": false,
 "aggregations": [
   {
     "type": "_type",
     "filter": "document"
   }
 ]
}

Behavior notes

• If the connected SearchUnify search client has GPT enabled, the tool returns enriched GPT context with links and descriptions.

• If GPT is not enabled, the tool returns standard search hits with fields such as title, summary, and URL.

• HTML tags are stripped from results automatically.

• If versionResults is supported in the response, the primary document appears instead of separate versioned documents.

Sample Response

{
 "content": [
   {
     "type": "text",
     "text": "title: How to Configure Search Clients\nsummary: Learn how to set up and manage search clients in SearchUnify.\nurl: https://docs.searchunify.com/search-clients\n---\ntitle: Content Sources Overview\nsummary: A guide to adding and managing content sources.\nurl: https://docs.searchunify.com/content-sources\n---"
   }
 ]
}

login

Use the login tool to start the tool-based SearchUnify MCP login flow.

This tool is used when an MCP-compatible AI client connects through the /mcp-connect endpoint. It is useful in environments where the browser does not open automatically or where the client needs to display a login link directly in the chat.

Availability

The login tool is available only on the /mcp-connect endpoint.

It is not available on:

• Standard OAuth endpoints

• Header-based authentication endpoints

Supported Parameters

The login tool does not require any parameters.

Behavior

When invoked, the tool returns a connection link. The user opens the link, enters the required SearchUnify connection details, and completes login in the browser.

After successful login, the remaining SearchUnify MCP tools become available for the session.

Sample Response

{
 "content": [
   {
     "type": "text",
     "text": "Please present this login link to the user so they can connect their SearchUnify instance:\n\n[Connect SearchUnify](https://mcp.searchunify.com/mcp-connect/login?s=<session_id>)\n\nIf your client supports clickable links, render the markdown above. Otherwise show the plain URL so the user can copy it. After the user completes login in their browser, let them know you are ready to continue."
   }
 ]
}

User Login Fields

The user is asked to provide the following details on the SearchUnify MCP connection page:

Important: For hosted SearchUnify MCP, the OAuth Client should use the MCP callback URL:

https://mcp.searchunify.com/su-callback

Recommended Use

Use login when:

• The client connects to /mcp-connect.

• The browser-based OAuth flow does not open automatically.

• The AI client needs to display a login link inside the conversation.

• The user needs to manually complete SearchUnify MCP login.

The /mcp-connect is specifically intended for tool-based login and returns a clickable connection link in the chat.

get-filter-options

Use the get-filter-options tool to retrieve available filters or facets for a search query. This tool is useful when the user wants to narrow a search by source, content type, category, product, index, or another configured facet.

Supported parameters

Example Request

{
 "searchString": "case deflection",
 "aggregations": [
   {
     "type": "_index",
     "filter": "Documentation"
   }
 ]
}

Response structure

The tool returns an array of aggregation groups.

Each aggregation group can include the following fields:

Each item in values can include:

Sample Response

{
 "content": [
   {
     "type": "text",
     "text": "[{\"key\":\"_index\",\"label\":\"Content Source\",\"order\":1,\"values\":[{\"displayName\":\"Documentation\",\"value\":\"Documentation\",\"contentName\":\"Docs\"},{\"displayName\":\"Community\",\"value\":\"Community\",\"contentName\":\"Community\"}]},{\"key\":\"_type\",\"label\":\"Content Type\",\"order\":2,\"values\":[{\"displayName\":\"Document\",\"value\":\"document\",\"contentName\":\"Document\"}]}]"
   }
 ]
}

Recommended Usage Pattern

A common search refinement flow is:

• Call get-filter-options with the user’s query.

• Review the available filters.

• Ask the user which filters to apply, if needed.

• Pass the selected filters into the search tool through aggregations.

Example:

User: Search for SSO setup articles and show me the available filters.

Assistant: Calls get-filter-options.

Assistant: Presents available filters.

User: Limit it to documentation.

Assistant: Calls search with the selected aggregation.

It is recommended to use get-filter-options before search when an assistant needs to discover available filters and then pass selected filters into the search request.

analytics

Use the analytics tool to retrieve SearchUnify analytics reports.

This tool is intended for reporting workflows, search quality analysis, and content optimization use cases.

Supported Parameters

Supported Report Types

Note: For `sessionDetails` and `sessionListTable`, if `sortByField` is set to `count`, SearchUnify MCP sends it as `click` to the underlying analytics API.

Example Request

{
 "reportType": "searchQueryWithoutResults",
 "startDate": "2026-04-01",
 "endDate": "2026-04-30",
 "count": 20
}

Sample Response

{
 "content": [
   {
     "type": "text",
     "text": "query: reset password\ncount: 42\n---\nquery: configure saml\ncount: 31\n---\nquery: search client uid\ncount: 18\n---"
   }
 ]
}

Recommended Use Cases

Use analytics to:

• Identify zero-result queries.

• Find searches that returned results but received no clicks.

• Review popular search queries.

• Analyze search conversions.

• Review average click position.

• Investigate session-level activity.

get-search-clients

Use the get-search-clients tool to list the search clients configured in the connected SearchUnify instance.

This tool is useful when the user or administrator does not know which Search Client UID to use while configuring SearchUnify MCP.

Supported Parameters

The get-search-clients tool does not require any parameters.

Behavior

The tenant is derived from the authentication credentials used to connect SearchUnify MCP.

The tool returns minimal information about available search clients, including the search client name and UID.

Response Structure

Each search client can include the following fields:

Sample Response

{
 "content": [
   {
     "type": "text",
     "text": "[{\"id\":\"101\",\"name\":\"Documentation Search\",\"uid\":\"8f8b0c7e-0000-0000-0000-000000000000\",\"search_client_type\":\"Web App\"},{\"id\":\"102\",\"name\":\"Support Portal Search\",\"uid\":\"7d7a0b6d-0000-0000-0000-000000000000\",\"search_client_type\":\"Salesforce\"}]"
   }
 ]
}

Recommended Use

Use get-search-clients when:

• The user does not know the Search Client UID.

• An administrator needs to identify which search client to connect to MCP.

• A developer wants to verify that the authentication credentials can access the expected SearchUnify instance.

• The tool lists search clients configured in the connected SearchUnify instance. Each returned search client can include fields such as id, name, uid, and search_client_type.

Standard MCP Response Format

SearchUnify MCP tools return responses using the standard MCP content structure.

A typical response contains a content array. Each item in the array has a type and a text value.

Standard Response Example

{
 "content": [
   {
     "type": "text",
     "text": "title: How to Configure Search Clients\nsummary: Learn how to set up and manage search clients in SearchUnify.\nurl: https://docs.searchunify.com/search-clients\n---"
   }
 ]
}

Response Behavior

Successful tool responses use the standard MCP content array. The returned text can vary based on the SearchUnify search client configuration and the tool invoked.

Tool Selection Guide

Use the following guide to decide which tool to invoke:

Example Workflows

Search with Filters

User asks: Find documentation about SSO and show only documentation results.

1. Call get-filter-options with searchString = "SSO".

2. Identify the relevant documentation filter.

3. Call search with searchString = "SSO" and the selected aggregation.

4. Return the filtered search results.

Tool-Based Login

User asks: Connect my SearchUnify instance.

1. MCP client connects to the /mcp-connect endpoint.

2. Call login.

3. Show the returned connection link to the user.

4. User completes login in the browser.

5. Continue using search, get-filter-options, analytics, or get-search-clients.

Find a Search Client UID

User asks: Which Search Client UID should I use?

1. Call get-search-clients.

2. Review the available search clients.

3. Select the correct UID based on the client name and type.

Search Analytics Review

User asks: Show me the top zero-result queries from April.

1. Call analytics.

2. Set reportType = searchQueryWithoutResults.

3. Set startDate and endDate.

4. Set count.

5. Return the analytics results.