The Searchcraft MCP Server provides a suite of tools for managing your Searchcraft cluster's Documents, Indexes, Federations, Access Keys, and Analytics. It enables MCP Clients, like Claude Desktop, to be prompted in plain English to perform administrative actions like setting up search indexes, access keys, ingesting documents, viewing analytics, searching indexes, and more.
Sample Prompts
Here is a sample prompt that could be used once Claude is connected to the Searchcraft MCP Server.
Available Tools
The Searchcraft MCP Server currently provides three categories of tools, import tools, engine api tools, and app generation tools:
Engine API Tools
These tools provide direct access to your Searchcraft cluster's core functionality for managing indexes, documents, federations, authentication, and search operations.
Index Management
Tool Name | Description |
create_index | Create a new index with the specified schema. This will empty the index if it already exists. |
delete_index | Delete an index and all its documents permanently. |
get_all_index_stats | Get document counts and statistics for all indexes. |
get_index_schema | Get the schema definition for a specific index. |
get_index_stats | Get statistics and metadata for a specific index (document count, etc.). |
list_all_indexes | Get a list of all indexes in the Searchcraft instance. |
patch_index | Make partial configuration changes to an index schema (search_fields, weight_multipliers, etc.). |
update_index | Replace the entire contents of an existing index with a new schema definition. |
Document Management
Tool Name | Description |
add_documents | Add one or multiple documents to an index. Documents should be provided as an array of JSON objects. |
delete_all_documents | Delete all documents from an index. The index will continue to exist after all documents are deleted. |
delete_document_by_id | Delete a single document from an index by its internal Searchcraft ID (_id). |
delete_documents_by_field | Delete one or several documents from an index by field term match (e.g., {id: 'xyz'} or {title: 'foo'}). |
delete_documents_by_query | Delete one or several documents from an index by query match. |
get_document_by_id | Get a single document from an index by its internal Searchcraft ID (_id). |
Federation Management
Tool Name | Description |
create_federation | Create or update a federation with the specified configuration. |
delete_federation | Delete a federation permanently. |
get_federation_details | Get detailed information for a specific federation. |
get_federation_stats | Get document counts per index for a federation as well as the total document count. |
get_organization_federations | Get a list of all federations for a specific organization. |
list_all_federations | Get a list of all federations in the Searchcraft instance. |
update_federation | Replace the current federation entity with an updated one. |
Authentication & Key Management
Tool Name | Description |
create_key | Create a new authentication key with specified permissions and access controls. |
delete_all_keys | Delete all authentication keys on the Searchcraft cluster. Use with extreme caution! |
delete_key | Delete a specific authentication key permanently. |
get_application_keys | Get a list of all authentication keys associated with a specific application. |
get_federation_keys | Get a list of all authentication keys associated with a specific federation. |
get_key_details | Get detailed information for a specific authentication key. |
get_organization_keys | Get a list of all authentication keys associated with a specific organization. |
list_all_keys | Get a list of all authentication keys on the Searchcraft cluster. |
update_key | Update an existing authentication key with new configuration. |
Stopwords Management
Tool Name | Description |
add_stopwords | Add custom stopwords to an index. These are added on top of the default language-specific dictionary. |
delete_all_stopwords | Delete all custom stopwords from an index. This only affects custom stopwords, not the default language dictionary. |
delete_stopwords | Delete specific custom stopwords from an index. This only affects custom stopwords, not the default language dictionary. |
get_index_stopwords | Get all stopwords for an index, including both default language dictionary and custom stopwords. |
Synonyms Management
Tool Name | Description |
add_synonyms | Add synonyms to an index. Synonyms only work with fuzzy queries, not exact match queries. |
delete_all_synonyms | Delete all synonyms from an index. |
delete_synonyms | Delete specific synonyms from an index by their keys. |
get_index_synonyms | Get all synonyms defined for an index. |
Search & Analytics
Tool Name | Description |
get_measure_conversion | Get measurement conversion data with optional filtering and aggregation parameters. *requires Clickhouse if running locally |
get_measure_summary | Get measurement summary data with optional filtering and aggregation parameters. *requires Clickhouse if running locally |
get_search_results | Performs a search query using the Searchcraft API with support for fuzzy/exact matching, facets, and date ranges. |
get_prelim_search_data | Get schema fields and facet information for a search index to understand available fields for constructing queries. |
get_searchcraft_status | Get the current status of the Searchcraft search service. |
Import Tools
These tools provide workflows for importing JSON data and automatically generating Searchcraft schemas. Perfect for quickly setting up new indexes from existing data sources.
Tool Name | Description |
analyze_json_from_file | Read JSON data from a local file and analyze its structure to understand field types and patterns for Searchcraft index schema generation. |
analyze_json_from_url | Fetch JSON data from a URL and analyze its structure to understand field types and patterns for Searchcraft index schema generation. |
generate_searchcraft_schema | Generate a complete Searchcraft index schema from analyzed JSON structure, with customizable options for search fields, weights, and other index settings. |
create_index_from_json | Complete workflow to create a Searchcraft index from JSON data. Fetches JSON from URL or file, analyzes structure, generates schema, creates the index, and adds all documents in one step. |
Import Tools Workflow
The import tools are designed to work together in a streamlined workflow:
Analyze → Use
analyze_json_from_file
oranalyze_json_from_url
to examine your JSON data structureGenerate → Use
generate_searchcraft_schema
to create a customized Searchcraft schema from the analysisCreate → Use the Engine API
create_index
tool to create the index with your generated schemaImport → Use
add_documents
to populate your new index with data
Or use the all-in-one approach:
One-Step → Use
create_index_from_json
to analyze, generate schema, create the index, and import all documents in one command
App Generation Tools
These tools create complete, ready-to-run search applications from your JSON data, perfect for prototyping and demos.
Tool Name | Description |
create_vite_app | Creates a complete Vite + React search application from JSON data. Analyzes your data structure, generates optimized search templates, and creates a fully functional web app with Searchcraft integration. |
App Generation Workflow
The app generation tools provide an end-to-end solution for creating search applications:
Data Analysis → Automatically analyzes your JSON structure to understand field types and content
Template Generation → Creates optimized search result templates based on your data fields
App Creation → Clones and configures a complete Vite + React application
Environment Setup → Configures Searchcraft connection settings
Ready to Run → Provides a fully functional search app you can immediately start and customize
Detailed Tool Usage
Using create_index_from_json
The create_index_from_json
tool provides a complete workflow to create a Searchcraft index from JSON data in a single command. This is perfect for quickly setting up search indexes from existing datasets. Note, if you know the language of the data you are importing you should specify it with the language
parameter (use the ISO 639-1 two letter code for the language)
Parameters
Parameter | Type | Required | Description |
|
or
| ✅ | Whether to fetch data from a URL or read from a local file |
|
| ✅ | URL or file path to the JSON data |
|
| ✅ | Name for the new Searchcraft index |
|
| ❌ | Number of items to analyze for schema generation (default: 10) |
|
| ❌ | Override automatically detected search fields |
|
| ❌ | Custom field weights for search relevance (0.0-10.0) |
|
| ❌ | Language code for the index (e.g., "en", "es") |
|
| ❌ | Auto commit delay in seconds |
|
| ❌ | Whether to exclude stop words from search |
|
| ❌ | Field name for time-based relevance decay |
Example Usage
From a URL:
From a local file:
What it does
Fetches/Reads Data → Downloads from URL or reads from local file
Analyzes Structure → Examines JSON to understand field types and patterns
Generates Schema → Creates optimized Searchcraft index schema
Creates Index → Sets up the index in your Searchcraft cluster
Imports Documents → Adds all JSON data as searchable documents
Returns Summary → Provides detailed information about what was created
Expected JSON Format
The tool works with various JSON structures:
Array of objects:
[{...}, {...}, ...]
Object with array property:
{"data": [{...}, {...}], "meta": {...}}
Single object:
{...}
(will be treated as a single document)
The tool automatically finds the best array of objects to use for the index.
Using create_vite_app
The create_vite_app
tool creates a complete, ready-to-run search application from your JSON data. It's perfect for quickly prototyping search interfaces or creating demo applications.
Parameters
Parameter | Type | Required | Description |
|
or
| ✅ | Whether to fetch data from a URL or read from a local file |
|
| ✅ | URL or file path to the JSON data |
|
| ✅ | Name for the generated app (used for directory name) |
|
| ✅ | Your Searchcraft cluster endpoint URL |
|
| ✅ | The Searchcraft index name to connect to |
|
| ✅ | Searchcraft read key for the application |
|
| ❌ | Number of items to analyze for template generation (default: 50) |
|
| ❌ | Override automatically detected search fields |
|
| ❌ | Custom field weights for search relevance (0.0-10.0) |
Example Usage
If you saw the prompt earlier in the documentation you can easily use the create_vite_app
tool with natural language. However, you want finer grain control you can use the tool with JSON parameters.
Creating a product search app:
Creating a blog search app from local data:
What it does
Analyzes Data Structure → Examines your JSON to understand field types and content patterns
Generates Search Templates → Creates optimized result display templates based on your data
Clones Vite Template → Downloads the official Searchcraft Vite + React template
Installs Dependencies → Sets up all required npm packages
Configures Environment → Creates
.env
file with your Searchcraft settingsCustomizes Templates → Generates dynamic search result components
Updates App Code → Modifies the main app with your specific branding and configuration
Generated App Features
The created application includes:
React + Vite → Modern, fast development setup
Searchcraft SDK Integration → Full search functionality out of the box
Responsive Design → Works on desktop and mobile devices
Auto-generated Templates → Smart result display based on your data structure
Environment Configuration → Easy setup for different environments
Development Server → Hot reload for rapid customization
Template Generation Logic
The tool intelligently analyzes your data to create optimal search result templates:
Title Field Detection → Finds the best field to use as the main title
Description Field Detection → Identifies descriptive text fields
Image Field Detection → Locates image URLs for visual results
Date Field Detection → Finds timestamp fields for temporal sorting
Additional Fields → Includes other relevant text fields for comprehensive results
Next Steps After Creation
Once the app is created, you can:
Start Vite Server:
cd apps/your-app-name yarn devCustomize Styling → Modify CSS and components to match your brand
Add Features → Extend with filters, facets, or advanced search options
Deploy → Build and deploy to your preferred hosting platform
Prerequisites
Existing Searchcraft Index → The index specified in
VITE_INDEX_NAME
should already existValid Read Key → The
VITE_READ_KEY
must have read permissions for the indexGit Available → The tool uses git to clone the template repository
Node.js & Yarn → Required for dependency installation
Complete Workflow: From JSON to Search App
Here's how to use both tools together to go from raw JSON data to a fully functional search application:
Option 1: Two-Step Process (Recommended for Production)
Step 1: Create the Searchcraft Index
Step 2: Create the Search Application
Option 2: App-Only Process (For Existing Indexes)
If you already have a Searchcraft index set up, you can jump straight to creating the app:
Benefits of the Two-Step Approach
Index Optimization → Fine-tune your search index separately from the UI
Multiple Apps → Create different search interfaces for the same data
Production Ready → Better separation of concerns for production deployments
Easier Debugging → Test search functionality independently of the UI
Getting Started
Environment Variables
Create .env
file at the project's root and fill in the values:
Remote Usage
If you have already created an index through Vektron on Searchcraft Cloud you may use the write key for the index you are trying to access and use the MCP server for API operations that don't require admin privileges. IMPORTANT: If you use the MCP server with a write key it should NOT be publicly exposed to the internet. Write keys are intended to be secured and by running an MCP server any user with access to the MCP server will be able to write to the index or delete data.
Installation & Setup
Make sure your environment has the correct version of node selected.
Install dependencies with yarn
Build the server
This creates two server versions:
dist/server.js
- HTTP server for testing and remote deploymentdist/stdio-server.js
- stdio server for Claude Desktop
Usage
Option 1: Claude Desktop (stdio) - Recommended
For local use with Claude Desktop, use the stdio version which provides better performance and reliability.
claude_desktop_config.json
The claude desktop config file can be found at:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
If the file doesn't exist, create it.
Option 2: Claude Code
For use with Claude Code, use the CLI to configure the MCP server:
Basic setup:
With environment variables:
Configuration scopes:
--scope local
(default): Available only to you in the current project--scope project
: Shared with team via.mcp.json
file (recommended for teams)--scope user
: Available to you across all projects
Managing servers:
Option 3: Open WebUI (via Pipelines)
Open WebUI supports MCP servers through its Pipelines framework. This requires creating a custom pipeline that bridges your MCP server to Open WebUI.
Step 1: Start the Searchcraft MCP HTTP server
Step 2: Create an MCP Pipeline for Open WebUI
Create a file called searchcraft_mcp_pipeline.py
:
Step 3: Install the Pipeline in Open WebUI
Via Admin Panel:
Go to Admin Settings → Pipelines
Click "Add Pipeline"
Paste the pipeline code above
Configure the valves with your Searchcraft settings:
MCP_SERVER_URL
:http://localhost:3100/mcp
ENDPOINT_URL
: Your Searchcraft cluster URLADMIN_KEY
: Your Searchcraft admin key
Via Docker Environment:
# Save the pipeline to a file and mount it docker run -d -p 3000:8080 \ -v open-webui:/app/backend/data \ -v ./searchcraft_mcp_pipeline.py:/app/backend/data/pipelines/searchcraft_mcp_pipeline.py \ --name open-webui \ ghcr.io/open-webui/open-webui:main
Step 4: Configure Open WebUI to use Pipelines
Start Open WebUI with Pipelines support:
# Using Docker Compose (recommended) services: openwebui: image: ghcr.io/open-webui/open-webui:main ports: - "3000:8080" volumes: - open-webui:/app/backend/data environment: - OPENAI_API_BASE_URL=http://pipelines:9099 - OPENAI_API_KEY=0p3n-w3bu! pipelines: image: ghcr.io/open-webui/pipelines:main volumes: - pipelines:/app/pipelines environment: - PIPELINES_API_KEY=0p3n-w3bu!In Open WebUI Settings → Connections:
Set OpenAI API URL to your Pipelines instance
Enable the Searchcraft MCP Pipeline
Option 4: HTTP Server (for testing/remote deployment)
Start the HTTP server for testing, debugging, or remote deployment:
For Claude Desktop with HTTP server, you'll need mcp-remote:
claude_desktop_config.json
Available Scripts
stdio vs HTTP: Which to Choose?
Feature | stdio (Recommended) | HTTP |
Performance | ✅ Direct IPC, lower latency | ⚠️ HTTP overhead |
Security | ✅ No exposed ports | ⚠️ Network port required |
Simplicity | ✅ No port management | ⚠️ Port conflicts possible |
Claude Desktop | ✅ Native support | ⚠️ Requires mcp-remote |
Claude Code | ✅ Native support | ✅ Native support |
Open WebUI | ❌ Not supported | ✅ Via Pipelines framework |
Remote Access | ❌ Local only | ✅ Can deploy remotely |
Testing | ⚠️ Requires MCP tools | ✅ Easy with curl/Postman |
Multiple Clients | ❌ One client at a time | ✅ Multiple concurrent clients |
Use stdio when:
Using Claude Desktop or Claude Code locally
You want the best performance
You prefer simplicity
Use HTTP when:
You need remote access
You want easy testing/debugging
You need multiple concurrent clients
You're deploying to a server
Using Open WebUI or other web-based interfaces
Debugging
Claude Desktop Logs
To view Claude Desktop's logs for debugging MCP connections:
Testing with MCP Inspector
The MCP Inspector allows you to test your server tools interactively.
For stdio server (recommended):
Choose Transport Type: stdio
Command:
node dist/stdio-server.js
For HTTP server:
Choose Transport Type: Streamable HTTP
URL:
http://localhost:3100/mcp
Manual Testing
Test HTTP server:
Test stdio server:
Resources
Issues and Feature Requests
Visit https://github.com/searchcraft-inc/searchcraft-issues
License
Licensed under the Apache 2.0 License.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server that enables AI assistants like Claude Desktop to search and retrieve information from custom search indexes created with Searchcraft.
Related MCP Servers
- AsecurityAlicenseAqualityThe Search MCP Server enables seamless integration of network and local search capabilities in tools like Claude Desktop and Cursor, utilizing the Brave Search API for high-concurrency and asynchronous requests.Last updated -173MIT License
- -securityFlicense-qualityAn MCP server that allows AI assistants like Claude to execute terminal commands on the user's computer and return the output, functioning like a terminal through AI.Last updated -58
- -securityFlicense-qualityAn MCP server that integrates with Claude to provide smart documentation search capabilities across multiple AI/ML libraries, allowing users to retrieve and process technical information through natural language queries.Last updated -
- -securityAlicense-qualityAn MCP server that integrates with Sonar API to provide Claude with real-time web search capabilities for comprehensive research.Last updated -0MIT License