Skip to main content
Lucidworks MCP (Model Context Protocol) enables agentic search using Claude to search your Lucidworks Search data. You configure the connection once, and Claude can immediately search your indexed content.
Claude can connect to Lucidworks Search using MCP

​
Benefits

Lucidworks MCP server provides these advantages:
  • Self-service integration: Configure Claude to access Lucidworks Search data without custom API development.
  • Enterprise security: Leverages Lucidworks Search’s existing security controls, including field-level security, role-based access, and audit logging.
  • Multi-tenant architecture: Support multiple use cases with different data access patterns using query profiles and collection isolation.
  • Query pipeline integration: Claude benefits from your custom query pipelines, ML models, and relevance tuning.
  • Extensible tool framework: Add custom tools programmatically that automatically become available to Claude.

​
Supported AI clients

Lucidworks MCP works with any MCP-compatible AI client, including these popular clients:
  • Claude Code - Command-line AI agent with built-in MCP support (recommended for easiest setup).
  • Claude Desktop - Desktop application for conversational AI.

​
MCP server setup

​
Before you begin

Before configuring MCP access, ensure you have the following:
  • Lucidworks Search 5.17 or later deployed with the MCP Server service running
  • A Lucidworks Search app configured with indexed content
  • A query profile created for MCP access
  • An API key generated in Lucidworks Search with appropriate permissions
  • Claude Code (recommended) or Claude Desktop
The MCP server runs on your Lucidworks Search infrastructure at https://FUSION_HOST/mcp.

​
Configure the MCP server

If you are using Lucidworks Search, the Lucidworks team configures the MCP server for you. You can work with Lucidworks to define search experiences that map to specific Lucidworks Search applications and query profiles.

​
Connect an AI agent

To connect an AI agent to Lucidworks Search, you need your Lucidworks Search API key for authentication. The key is sent as an HTTP header with each request.
Claude Code provides easy setup with a single command.
1

Add the Lucidworks MCP server

claude mcp add --transport http fusion https://FUSION_HOST/mcp --header "x-api-key: FUSION_API_KEY"
Replace the placeholder values with your Lucidworks Search host, port, and API key.
If you receive errors when running this command, check your Claude Code version. The --transport and --scope flags require a recent version of Claude Code.
By default, MCP servers are scoped to the current project. To make the server available globally across all projects, add --scope user. To explicitly scope it to the current project, add --scope project.
2

Verify the configuration

claude mcp list
You should see fusion listed, with the HTTP transport.
Lucidworks provides an MCP Bundle (.mcpb) file that enables easy setup; this is the recommended method. Alternatively, you can configure Claude Desktop manually by editing the JSON configuration file.

​
Test the connection

After configuring your AI agent, test the connection with these example prompts. These prompts verify that the MCP server is working correctly and that Claude can discover and use the configured search experiences.
1

Retrieve search experiences

Test whether Claude can successfully retrieve the configured search experiences from Lucidworks Search.

What search experiences are available?

2

Search by name

Test whether Claude can identify the correct search experience by name and execute a search query.

Search the Product Catalog for wireless headphones

3

Test multi-experience routing

Test multi-experience routing, verifying that Claude can select the appropriate search experience based on the query context.

Find recent HR policies in Employee Resources

4

Match natural language queries

Test whether Claude can match natural language queries to search experience descriptions and return relevant results.

What information can I find about benefits and time off policies?

​
Search with MCP

Lucidworks MCP server provides four tools that work together in a discovery-to-execution pattern. Claude automatically determines which tool to call based on the user’s query.

​
List search experiences

The list_search_experiences tool discovers available search experiences configured in Lucidworks Search. You can use this tool in the following situations:
  • You need to see what search experiences are available.
  • You need to determine which search experience to use for a specific query.
  • You need to help users who don’t know what they can search for.
Claude automatically calls this tool when users ask questions like “What can I search here?” or “What do I find in Lucidworks Search?”. The tool returns a list of configured search experiences with their names and descriptions. This tool takes no parameters.

​
Search documents

The search_documents tool searches for documents and returns relevant results from Lucidworks Search collections. Based on user input, it automatically selects a search experience and can optionally filter and sort results. For example, a user can input “Find all reports from the last six months and sort them with the newest ones first” to trigger a query that uses filters to specify the document type and date range and sort to order the results by date, newest to oldest.

​
Get a document

The get_document tool fetches a specific document by its ID. This is useful when search_documents has already been called and the user inquires about a specific document returned in those results. The tool returns complete details about the document, such as its title, description, URL, similar documents (if MoreLikeThis is implemented), and highlighted fields (if highlighting is implemented).

​
Get the field schema

The get_schema tool retrieves available fields within a specific search experience and returns schema information with sortable and searchable capability flags. You can use this tool in the following situations:
  • You need to discover what fields exist within a particular search experience.
  • You need to determine which fields can be used for sorting.
  • You need to determine which fields can be used for filtering.
  • You need to display field information to users with human-readable names.
Claude automatically calls this tool before using the sort or filters parameters when searching documents, or when users ask questions like “What fields can I sort by?” or “What can I filter by?”. The tool returns field names with their display values and capability flags. By default, the tool returns only populated fields. Set includeEmptyFields=true to retrieve the complete schema.

​
How the tools work together

Claude uses these tools in the following order:
  1. When a user asks a question without specifying a search experience, Claude calls list_search_experiences to discover available options.
  2. Claude analyzes the search experiences and matches them to the user’s query intent.
  3. Claude calls search_documents with the appropriate search experience.
  4. Claude returns results to the user.
For example, when a user asks “Find hiking backpacks,” Claude automatically completes the following steps:
  1. Calls list_search_experiences and receives the following data: 
    {
  "searchExperiences": [
    {"name": "Product Catalog", "description": "Outdoor gear and sporting equipment"},
    {"name": "Support Articles", "description": "Product guides, warranties, and care instructions"}
  ]
}
  2. Identifies the “Product Catalog” search experience as the one that best matches the prompt.
  3. Calls search_documents with searchExperience: "Product Catalog" and the user’s query.
  4. Returns the product results.
This pattern allows users who know nothing about Lucidworks Search’s configuration to simply ask questions and get results without needing to understand the underlying structure.

​
Example use cases

The following examples demonstrate common MCP integration patterns.
If your query pipeline is configured with highlighting or MoreLikeThis, the MCP server can include those features in its responses:
Example response
{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [],
    "isError": false,
    "structuredContent": {
      "summary": "Found 3 documents for query: search",
      "documents": [
        {
          "id": "doc-123",
          "title": "Introduction to Search Analytics",
          "url": "https://docs.example.com/search-analytics",
          "moreLikeThis": [
            {
              "id": "doc-456",
              "title": "Query Performance Optimization"
            },
            {
              "id": "doc-789",
              "title": "Relevance Tuning Best Practices"
            },
            {
              "id": "doc-321",
              "title": "Understanding Search Metrics"
            }
          ],
          "highlighting": {
            "title_t": ["Introduction to <em>Search</em> Analytics"],
            "description_t": ["Learn how to analyze and improve your <em>search</em> performance"]
          }
        }
      ],
      "searchExperiences": [],
      "querySpellcheckSuggestions": []
    }
  }
}

​
Example multi-tenant configurations

Lucidworks MCP server supports multi-tenant architectures where different users or use cases access different data subsets.
You can configure separate MCP endpoints with different query profiles:
claude mcp add --transport http fusion-employee \
    https://FUSION_HOST/mcp \
    --header "x-api-key: EMPLOYEE_KEY"
  • The employee API key accesses a server with search experiences configured for full access to all collections.
  • The contractor API key accesses a server with search experiences limited to public documentation and shared resources.
You can support both public (unauthenticated) and authenticated access patterns:
{
  "mcpServers": {
    "fusion-public": {
      "type": "http",
      "url": "https://FUSION_HOST/mcp",
      "headers": {
        "x-api-key": "PUBLIC_READONLY_KEY"
      }
    }
  }
}
This approach enables use cases like showroom kiosks (public read-only access with search experiences configured for public documents) and internal employee tools (authenticated with search experiences configured for full access and security trimming) using the same Lucidworks Search instance.

​
Troubleshooting

This section provides solutions for common MCP configuration issues.
If you cannot connect to the MCP server, verify the following:
  1. Verify the endpoint is accessible: 
     curl -X POST https://FUSION_HOST/mcp \
 -H "Content-Type: application/json" \
 -H "Accept: text/event-stream, application/json" \
 -H "x-api-key: API_KEY" \
 -i \
 -d '{
   "jsonrpc": "2.0",
   "id": 1,
   "method": "initialize",
   "params": {
     "protocolVersion": "2025-11-25",
     "capabilities": {},
     "clientInfo": {
       "name": "test-client",
       "version": "1.0.0"
     }
   }
 }'
    The protocol version in this example (2025-11-25) may differ from your installed version. See the MCP schema specification for the current version.
    If the endpoint is accessible, it returns output similar to the example below. Any other result means that the endpoint is not accessible. 
    {
 "jsonrpc": "2.0",
 "id": 1,
 "result": {
   "protocolVersion": "2024-11-05",
   "capabilities": {
     "logging": {},
     "prompts": {
       "listChanged": false
     },
     "resources": {
       "subscribe": false,
       "listChanged": true
     },
     "tools": {
       "listChanged": true
     }
   },
   "serverInfo": {
     "name": "Lucidworks MCP Server",
     "version": "1.0.0"
   }
 }
}

2. Confirm that the Lucidworks Search version is 5.17 or later:
 ```bash wrap
 curl https://FUSION_HOST:FUSION_PORT/api/admin/version
  1. Check the URL path is exactly /mcp (no trailing slash, not /api/mcp).
  2. Test with verbose logging: 
    claude mcp test fusion --verbose
  1. Regenerate the API key in Lucidworks Search Admin (the key may be expired or revoked).
  2. Verify the header format is exactly x-api-key: API_KEY (case-sensitive).
  3. Test the key directly against Lucidworks Search’s API: 
    curl -H "x-api-key: abc123" https://FUSION_HOST:FUSION_PORT/api/apps/YOUR_APP/query/YOUR_PROFILE
  1. Verify the query profile exists in the specified Lucidworks Search app.
  2. Check the profile name is an exact match (case-sensitive).
  3. Ensure the API key’s role has permission to execute queries on this profile.
The x-api-key header is required for authentication:
claude mcp add --transport http fusion https://FUSION_HOST/mcp --header "x-api-key: API_KEY"
Run this command to verify your configuration:
claude mcp list
The response should show your MCP URL:
fusion - https://FUSION_HOST/mcp (http)
If searches complete successfully but return no results, try these steps.
  1. Verify the Lucidworks Search app contains indexed content: 
    curl "https://FUSION_HOST:FUSION_PORT/api/apps/YOUR_APP/query/YOUR_PROFILE?q=*:*"
  2. Check that the query profile has access to the expected collections.
  3. Test the same query directly in Lucidworks Search’s Query Workbench to confirm results exist.
  4. Review security trimming rules that might filter out documents for the API key’s role.
If MCP searches are slow, try these steps.
  1. Check the query profile’s pipeline stages for expensive operations.
  2. Review the query complexity (complex filter queries can impact performance).
  3. Monitor Lucidworks Search’s query logs for slow queries.
  4. Consider optimizing ML model execution or caching strategies.
  5. Verify network latency between Claude and Lucidworks Search instance.
  6. Contact Lucidworks if performance tuning is needed.
If list_search_experiences returns fewer search experiences than you configured, follow these steps.Solution:
  1. Check server startup logs for: INFO - Found N valid search experience(s): [names]
  2. Compare logged names with your configuration.
  3. Verify all required fields are populated (name, description, application-name, query-profile).
  4. Fix configuration and restart.
If your search query returns an error message about the search experience not being configured, verify the search experience name.Symptom:
{
  "summary": "Search experience is not configured",
  "documents": [],
  "searchExperiences": [...]
}
Solution:
  1. Call list_search_experiences to get exact names.
  2. Use the exact name (case-sensitive).
Common mistakes:
  • ❌ “engineering docs” (wrong case)
  • ✅ “Engineering Docs” (exact match)
If you receive a generic error message about being unable to process the request, verify your Lucidworks Search configuration and connectivity.Symptom:
{
  "content": [{"type": "text", "text": "Error: Unable to process request"}],
  "isError": true
}
Solution:Follow these troubleshooting steps:
  1. Verify Lucidworks Search is running and accessible.
  2. Check that application-name exists in Lucidworks Search (case-sensitive).
  3. Verify query-profile exists and is enabled in Lucidworks Search.
  4. Check authentication and network connectivity.
  5. Review MCP server logs for detailed error messages.
If your search completes successfully but returns no documents, verify your data and query configuration.Symptom:
{
  "summary": "Found 0 documents",
  "documents": [],
  "searchExperiences": []
}
Solution:Follow these troubleshooting steps:
  1. Verify documents are indexed in Lucidworks Search (check Collections in Lucidworks Search UI).
  2. Try omitting the query parameter to return all documents (defaults to *:*): 
    {
  "searchExperience": "Company Knowledge"
}
  3. Try a broader query.
  4. Test the same query directly in Query Workbench.
  5. Verify application-name points to the correct Lucidworks Search application.
  6. Check query profile settings for permission filters.