Searchcraft

You can run and connect to the Searchcraft MCP Server to manage your cluster’s documents, indexes, federations, keys, and analytics from your preferred MCP client. It enables you to create and configure indexes, ingest data, manage access, run searches, and automate administrative actions through friendly tools.

How to use

You interact with the MCP Server through your MCP client to perform administrative tasks. Start the stdio version for local, high-performance use with clients like Claude Desktop. When you connect, you’ll be able to create indexes, add documents, manage keys, and run searches against your cluster. Use the available tools to manage index schemas, document sets, stopwords, synonyms, and federation details, and to retrieve status and analytics.

How to install

Prerequisites

• Node.js installed (NVM is recommended to manage versions)
• Yarn package manager
• A valid Searchcraft cluster endpoint and API key if you plan to use remote operations Install and build the MCP Server locally, then run the stdio server for local development.

# 1) Use a compatible Node.js version
nvm use

# 2) Install dependencies
yarn

# 3) Build the server (stdio variant is included)
yarn build

# 4) Start the stdio server (stdio server runs the MCP server in-process)
yarn start:stdio

Configuration and usage notes

Environment configuration is needed to connect to your Searchcraft cluster. Create a configuration file (for example, a .env file) and supply the following variables. You will typically provide the endpoint URL of your Searchcraft cluster and a core API key with the appropriate permissions.

# Server Config
PORT=3100
DEBUG=true

# Searchcraft Config
ENDPOINT_URL=https://your-cluster.searchcraft.io
CORE_API_KEY=YOUR_API_KEY

Usage with Claude Desktop (stdio)

For local use with Claude Desktop, run the stdio server and point Claude to it using a local configuration. The stdio server runs as a separate process and communicates via standard input/output, offering best performance for desktop workflows.

{
  "mcpServers": {
    "searchcraft": {
      "command": "node",
      "args": [
        "/path/to/searchcraft-mcp-server/dist/stdio-server.js"
      ]
    }
  }
}

Usage with Claude Code

You can register the MCP server with Claude Code and optionally provide environment variables for your cluster connection.

claude mcp add searchcraft -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

With environment vars:

claude mcp add searchcraft \
  --env ENDPOINT_URL=https://your-cluster.searchcraft.io \
  --env CORE_API_KEY=YOUR_API_KEY \
  -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

Open WebUI and pipelines (optional)

If you use Open WebUI with pipelines, you can bridge the MCP server to the UI. Start the MCP HTTP server, then configure a pipeline to forward interactions to the MCP server.

Docker and remote deployment (optional)

You can containerize the MCP server for easier remote deployment. Build the Docker image and run the container with your cluster settings.

Testing and debugging

Test the MCP endpoint and health check to ensure the server is responding correctly. Use standard curl commands against the HTTP endpoint or inspect logs for debugging information.

Next steps

Once the server is running, connect your MCP client, explore index management, document operations, and key management, and begin building your administrative workflows around your Searchcraft cluster.

Available tools

create_index

Create a new index with the specified schema. This operation initializes or replaces an index with a given configuration.

delete_index

Delete an index and all its documents permanently.

get_all_index_stats

Retrieve document counts and statistics for all indexes in the instance.

get_index_schema

Fetch the schema definition for a specific index.

get_index_stats

Get statistics and metadata for a specific index, including document counts.

list_all_indexes

List all indexes in the Searchcraft instance.

patch_index

Apply partial updates to an index schema such as search fields and weight multipliers.

update_index

Replace an existing index with a new schema.

add_documents

Add one or multiple documents to an index.

delete_all_documents

Remove all documents from an index, leaving the index in place.

delete_document_by_id

Delete a single document by its internal identifier.

delete_documents_by_field

Delete documents that match a specific field value.

delete_documents_by_query

Delete documents that match a query.

get_document_by_id

Retrieve a single document by its internal identifier.

create_federation

Create or update a federation with a given 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 and totals.

get_organization_federations

List all federations for a specific organization.

list_all_federations

List all federations in the Searchcraft instance.

update_federation

Replace the current federation entity with updated data.

create_key

Create a new authentication key with specified permissions.

delete_all_keys

Delete all authentication keys on the cluster.

delete_key

Delete a specific authentication key.

get_application_keys

List all keys associated with a specific application.

get_federation_keys

List all keys for a specific federation.

get_key_details

Get detailed information for a specific authentication key.

get_organization_keys

List all keys for a specific organization.

list_all_keys

List all authentication keys on the cluster.

update_key

Update an existing authentication key with new configuration.

add_stopwords

Add custom stopwords to an index in addition to the default dictionaries.

delete_all_stopwords

Remove all custom stopwords from an index.

delete_stopwords

Delete specific custom stopwords from an index.

get_index_stopwords

Retrieve all stopwords, including defaults and custom additions.

add_synonyms

Add synonyms to an index to improve search relevance for fuzzy queries.

delete_all_synonyms

Remove all custom synonyms from an index.

delete_synonyms

Delete specific synonyms for an index by their keys.

get_index_synonyms

Get all synonyms defined for an index.

get_measure_conversion

Get measurement conversion data with optional filters and aggregations.

get_measure_summary

Get a summary of measurements with optional filters and aggregations.

get_search_results

Execute a search query with fuzzy or exact matching, facets, and date ranges.

get_prelim_search_data

Fetch schema fields and facet information to understand available search fields.

get_searchcraft_status

Check the current status of the Searchcraft search service.

analyze_json_from_file

Analyze JSON data from a local file to infer field types for schema generation.

analyze_json_from_url

Analyze JSON data from a URL to infer field types for schema generation.

generate_searchcraft_schema

Generate a complete index schema from analyzed JSON structure with customizable options.

create_index_from_json

Create an index from JSON data by analyzing, generating a schema, creating the index, and importing documents in one step.

create_vite_app

Create a complete Vite + React app configured to use your Searchcraft index.