Set Up SearchUnify MCP

This article explains the process to configure the SearchUnify MCP for use with MCP-compatible clients. Before beginning, make sure you have the following:

  • your SearchUnify instance URL,

  • a valid API key or supported OAuth credentials,

  • your Search Client UID,

  • the required API scope access,

  • an MCP-compatible client,

  • and Docker if you plan to use local stdio-based deployment.

Choose a transport

SearchUnify MCP supports two transport mechanisms. Choose the one that best matches your deployment model.

HTTP transport

Use HTTP transport when the MCP server is hosted remotely and the client connects over HTTP or HTTPS.

This option is best when:

  • the server is centrally hosted,

  • multiple users need to connect to the same deployment,

  • or your client supports remote MCP connectivity.

stdio transport

Use stdio transport when the MCP client should spawn the MCP server locally.

This option is best when:

  • the server is run on the user’s machine,

  • credentials are managed locally,

  • or the host expects a locally launched MCP server process.

Configure SearchUnify MCP over HTTP

Use the following configuration pattern when connecting to a remotely hosted SearchUnify MCP server:

Copy

JSON

{
  "mcpServers": {
    "su-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "${searchunify_instance}/su-mcp/",
        "--header", "searchunify-instance:${searchunify_instance}",
        "--header", "searchunify-timeout:60000",
        "--header", "searchunify-auth-type:apiKey",
        "--header", "searchunify-api-key:<YOUR_API_KEY>",
        "--header", "searchunify-uid:<YOUR_UID>"
      ]
    }
  }
}

Required headers

Header Description

searchunify-instance

Base URL of your SearchUnify instance

searchunify-timeout

Request timeout in milliseconds

searchunify-auth-type

Authentication method, such as apiKey

searchunify-api-key

API key used for authentication

searchunify-uid

Search Client UID

Important notes

  • To run su-mcp with mcp-remote, Node version 24 is required on the machine.

  • Header-based credential passing is useful for centrally hosted and stateless connection patterns.

Configure SearchUnify MCP over stdio

Use the following configuration when the MCP client should run SearchUnify MCP locally in Docker:

Copy

JSON

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

Replace <path_to_local_creds.json> with the absolute path to your local credentials file.

Credentials file format for stdio

When using stdio transport, provide a creds.json file in the following format:

Copy

JSON

{
  "instance": "https://yourcompany.searchunify.ai",
  "authType": "apiKey",
  "apiKey": "<YOUR_API_KEY>",
  "uid": "<YOUR_UID>",
  "timeout": "60000"
}

Authentication options

SearchUnify MCP supports the following authentication methods:

  • API Key

  • OAuth 2.0 Password Grant

  • OAuth 2.0 Client Credentials Grant

For most implementations, start with API key authentication unless your deployment specifically requires an OAuth-based flow.

Expected outcome

After configuration is complete:

  • your MCP-compatible client should detect SearchUnify MCP,

  • the server should appear as an available MCP server,

  • and the client should be able to discover the tools exposed by the server.

Next step

Once setup is complete, connect SearchUnify MCP to your MCP-compatible client and validate that tool discovery and search requests are working as expected.