Connect SearchUnify MCP to MCP-Compatible Clients

This article explains how to connect SearchUnify MCP to MCP-compatible clients using either remote HTTP transport or local stdio transport. Before connecting SearchUnify MCP to a client, make sure:

  • SearchUnify MCP is configured correctly,

  • you have the required authentication values,

  • and the client supports MCP server configuration.

Choose the right connection method

Select the transport based on how you want SearchUnify MCP to be deployed.

Use HTTP transport when:

  • SearchUnify MCP is hosted remotely,

  • you want a centrally managed deployment,

  • or your client supports remote MCP connection patterns.

Use stdio transport when:

  • the client should run SearchUnify MCP locally,

  • credentials are stored locally,

  • or the client expects a locally spawned MCP server.

Connect using HTTP

Use this configuration pattern when your client supports mcp-remote:

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>"
      ]
    }
  }
}

This approach is best when the MCP server is hosted centrally and shared across users or environments.

Connect using stdio

Use this configuration pattern when the client should run SearchUnify MCP locally through 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"
      ]
    }
  }
}

This approach is best when the user’s machine is responsible for starting the MCP server and storing credentials locally.

Troubleshooting common issues

The client does not detect the server

Check that:

  • the configuration JSON is valid,

  • the command referenced in the configuration is installed and available,

  • and the client supports MCP server configuration in the expected format.

Authentication fails

Verify:

  • the instance URL,

  • API key or OAuth values,

  • authentication type,

  • timeout value,

  • and Search Client UID.

Docker startup fails

Make sure:

  • Docker is installed,

  • Docker is running,

  • Docker is available in the system path,

  • and the credentials file path is absolute and mounted correctly.

HTTP connection fails

Verify that:

  • the SearchUnify MCP server is running with HTTP transport enabled,

  • the configured endpoint is reachable,

  • and all required headers are being passed correctly

Next step

After the connection is validated, review the available SearchUnify MCP tools and their supported request parameters.