Set Up SearchUnify MCP (Developers)

Developer Use is recommended when you want to configure SearchUnify MCP manually to an MCP-compatible AI client for local development, custom clients, remote MCP deployments, or testing.

The examples in this section use Claude Desktop because it supports local MCP server configuration through `claude_desktop_config.json`. However, the same setup patterns can be used with any MCP-compatible AI client that supports remote MCP servers, stdio servers, or custom MCP configuration, such as LibreChat.

If you are using another MCP-compatible client, refer to that client’s documentation for where to add the MCP server configuration. The SearchUnify MCP server URL, credentials, headers, Docker command, and local server options remain the same unless your client requires a different configuration format.

Developer Use supports the following setup methods:

SearchUnify MCP supports two transports: stdio for local MCP clients such as Claude Desktop, and HTTP for remote or cloud-based MCP clients. The server can also run both transports simultaneously.

https://github.com/searchunify/su-mcp/Related resource: SearchUnify MCP GitHub repository

Before You Begin

Before setting up SearchUnify MCP for developer use, make sure you have:

• A SearchUnify instance URL

• A Search Client UID

• Authentication credentials

• An MCP-compatible client, such as Claude Desktop

• Docker, if using Docker-based setup

• Node.js, if using mcp-remote or local Node.js setup

For Docker setup, use the SearchUnify MCP Docker image and mount a local `creds.json` file to `/app/src/input/creds.json` in the container.

For local Node.js setup, clone the SearchUnify MCP repository, install the required dependencies, and create the credentials file at `src/input/creds.json`.

Method 1: Connect with mcp-remote and Header Authentication

Use this method when you want an MCP-compatible AI client to connect to a remotely hosted SearchUnify MCP server. In this setup, the MCP server runs remotely, and credentials are passed as headers from the MCP client configuration file.

This method does not require a local creds.json file.

Important: `mcp-remote` requires Node.js 24 or later on the machine where the MCP client runs. For `mcp-remote` header authentication, use the root endpoint:

`https://mcp.searchunify.com/`

Do not use `/mcp` for header authentication. The `/mcp` endpoint is used for OAuth-based connections and expects an OAuth Bearer token.

MCP client configuration

Add the following MCP server configuration to your MCP client configuration file. For Claude Desktop, add it to claude_desktop_config.json.

{
 "mcpServers": {
   "su-mcp": {
     "command": "npx",
     "args": [
       "mcp-remote",
       "https://mcp.searchunify.com/",
       "--header",
       "searchunify-instance:<searchunify_instance_url>",
       "--header",
       "searchunify-timeout:60000",
       "--header",
       "searchunify-auth-type:<apiKey|password|clientCredentials>",
       "--header",
       "searchunify-api-key:<your_api_key>",
       "--header",
       "searchunify-uid:<search_client_uid>"
     ]
   }
 }
}

Header reference

Valid HTTP headers take priority over credentials stored in creds.json. If the required headers are missing or incomplete, SearchUnify MCP uses the credentials available in creds.json, if configured.

Method 2: Connect with Docker and creds.json

Use this method when you want to run SearchUnify MCP locally through Docker. In this setup:

• The MCP configuration is added to the MCP client configuration file.

• Authentication credentials are stored in a separate local creds.json file.

• The MCP-compatible client launches the MCP server through Docker.

This setup runs SearchUnify MCP locally through Docker and uses stdio to communicate with the MCP-compatible client.

Step 1: Create creds.json

Create a creds.json file on your machine.

API key authentication

{
 "instance": "<searchunify_instance_url>",
 "timeout": 60000,
 "authType": "apiKey",
 "apiKey": "<your_api_key>",
 "uid": "<search_client_uid>"
}

OAuth password authentication

{
 "instance": "<searchunify_instance_url>",
 "timeout": 60000,
 "authType": "password",
 "oauth2": {
   "username": "<your_email>",
   "password": "<your_password>",
   "clientId": "<your_client_id>",
   "clientSecret": "<your_client_secret>"
 },
 "uid": "<search_client_uid>"
}

OAuth client credentials authentication

{
 "instance": "<searchunify_instance_url>",
 "timeout": 60000,
 "authType": "clientCredentials",
 "oauth2": {
   "clientId": "<your_client_id>",
   "clientSecret": "<your_client_secret>"
 },
 "uid": "<search_client_uid>"
}

Step 2: Configure the MCP client

For Claude Desktop, locate the configuration file:

Add the following MCP server configuration. For Claude Desktop, add it to claude_desktop_config.json:

{
 "mcpServers": {
   "su-mcp": {
     "command": "docker",
     "args": [
       "run",
       "-i",
       "--rm",
       "-v",
       "<path_to_creds.json>:/app/src/input/creds.json:ro",
       "searchunifyutils/su-mcp"
     ]
   }
 }
}

Replace <path_to_creds.json> with the absolute path to your local creds.json file.

Step 3: Restart the MCP client

Restart your MCP-compatible client to apply the updated configuration. For Claude Desktop, fully quit and reopen the application.

Method 3: Connect with Tool-Based Login via /mcp-connect

Use this method when the standard OAuth flow does not work or when you want the MCP-compatible client to show a login link directly in the chat.

In this setup:

• The MCP-compatible client connects to the /mcp-connect endpoint.

• The client calls the login tool.

• The chat displays a Connect SearchUnify link.

• The user opens the link manually, enters SearchUnify connection details, and completes login in the browser.

• After login, the remaining SearchUnify MCP tools become available.

The login tool is available only through the /mcp-connect endpoint. It generates a SearchUnify connection link inside the MCP client so users can complete login manually in a browser.

Prerequisites

Before using /mcp-connect, make sure:

The MCP server has OAUTH_ENCRYPTION_KEY and MCP_ISSUER_URL configured.

An OAuth client is registered in SearchUnify.

The OAuth client includes the MCP callback URL as an allowed redirect URI.

For the hosted SearchUnify MCP server, use:

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

Make sure the OAuth Client includes the MCP callback URL as an allowed redirection URL. If the callback URL is not configured correctly, the MCP connection may not complete successfully.

MCP client configuration

{
 "mcpServers": {
   "su-mcp": {
     "command": "npx",
     "args": [
       "mcp-remote",
       "https://mcp.searchunify.com/mcp-connect"
     ]
   }
 }
}

First-time login

On first use, the MCP-compatible client calls the login tool and displays a connection link.

Click the link and enter:

After completing login in the browser, return to the MCP-compatible client. The SearchUnify MCP tools are available for the session.

The /mcp-connect session is time-bound. If the session expires, call the login tool again to generate a new connection link.

Method 4: Connect with a Local Node.js Clone

Use this method when you want to run the MCP server directly from a local clone of the GitHub repository. This is best for development, debugging, testing changes, or contributing to the MCP server.

In this setup:

• You clone the GitHub repository locally.

• You install dependencies.

• You create a local src/input/creds.json file.

• The MCP-compatible client runs the MCP server with Node.js.

• Local Node.js setup requires Node.js 18 or later. Node.js 20 or later is recommended.

Step 1: Clone and install

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

cd su-mcp

npm install

Step 2: Create the credentials file

Create the following file:

src/input/creds.json

Use one of the same credential formats described in Method 2: Connect with Docker and creds.json.

Step 3: Configure the MCP client

Add the following MCP server configuration to your MCP client configuration file. For Claude Desktop, add it to claude_desktop_config.json.

{
 "mcpServers": {
   "su-mcp": {
     "command": "node",
     "args": [
       "/absolute/path/to/su-mcp/src/index.js"
     ],
     "env": {
       "MCP_TRANSPORT": "stdio"
     }
   }
 }
}

Replace /absolute/path/to/su-mcp with the actual path where you cloned the repository.

For local MCP client usage, set MCP_TRANSPORT to stdio. If MCP_TRANSPORT is not set, SearchUnify MCP starts in both mode, which enables stdio and also starts an HTTP server on port 3000.

Step 4: Restart the MCP client

Restart your MCP-compatible client to apply the updated configuration. For Claude Desktop, fully quit and reopen the application.

SearchUnify MCP Tools and Response Formats

This article documents the tools exposed by SearchUnify MCP, their supported parameters, usage behavior, and standard response formats.

SearchUnify MCP exposes enterprise search, filtering, login, analytics, and search client discovery capabilities as MCP tools. These tools can be invoked by Claude, ChatGPT, LibreChat, Cursor, or any other MCP-compatible AI client, depending on the client’s MCP support and configuration.