Searchcraft MCP server for AI agents

The Searchcraft MCP Server provides tools for managing your Searchcraft cluster, enabling MCP clients like Claude Desktop to perform administrative actions through plain English prompts, such as creating search indexes, managing access keys, ingesting documents, and viewing analytics.

Installation and Setup

Environment Configuration

Create a .env file at the project's root with the following values:

# Server Config
USER_AGENT=searchcraft-mcp-server/<project-version>
DEBUG=true
PORT=3100

# Searchcraft Config
ENDPOINT_URL= # The endpoint url of your Searchcraft Cluster
ADMIN_KEY= # The admin key (super user key) of your Searchcraft Cluster

Running the Server

First, make sure your environment has the correct version of Node.js:

nvm use

Install dependencies:

yarn

Build and start the server:

yarn build
yarn start

Connecting with Claude Desktop

The server must be running for Claude Desktop to detect the Searchcraft MCP Server's tools.

Add the following configuration to your Claude Desktop config file (located at /Users/[My Workspace]/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "searchcraft": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:<MY-PORT-FROM-ENV>/mcp"
      ]
    }
  }
}

Note on Node Versions

Ensure your default Node version is compatible with the server requirements, as Claude Desktop may sometimes use older versions of Node when connecting to the MCP server.

Available Tools

Index Management

create_index: Create a new index with the specified schema
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
list_all_indexes: Get a list of all indexes in the Searchcraft instance
patch_index: Make partial configuration changes to an index schema
update_index: Replace the entire contents of an existing index with a new schema definition

Document Management

add_documents: Add one or multiple documents to an index
delete_all_documents: Delete all documents from an index
delete_document_by_id: Delete a single document by its internal Searchcraft ID
delete_documents_by_field: Delete documents by field term match
delete_documents_by_query: Delete documents by query match
get_document_by_id: Get a single document by its internal Searchcraft ID

Federation Management

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
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

create_key: Create a new authentication key with specified permissions
delete_all_keys: Delete all authentication keys on the Searchcraft cluster
delete_key: Delete a specific authentication key permanently
get_application_keys: Get keys associated with a specific application
get_federation_keys: Get keys associated with a specific federation
get_key_details: Get detailed information for a specific authentication key
get_organization_keys: Get keys associated with a specific organization
list_all_keys: Get a list of all authentication keys
update_key: Update an existing authentication key with new configuration

Stopwords Management

add_stopwords: Add custom stopwords to an index
delete_all_stopwords: Delete all custom stopwords from an index
delete_stopwords: Delete specific custom stopwords from an index
get_index_stopwords: Get all stopwords for an index

Synonyms Management

add_synonyms: Add synonyms to an index
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 & Measurement

get_measure_conversion: Get measurement conversion data
get_measure_summary: Get measurement summary data
get_search_results: Performs a search query using the Searchcraft API
get_searchcraft_status: Get the current status of the Searchcraft search service

Debugging

To view Claude's logs for debugging purposes:

yarn claude-logs

Using the Inspector Tool

While the MCP server is running, you can launch the inspector to test tools:

yarn inspect

Choose Transport Type: Streamable HTTP
Specify the URL: http://localhost:<MY-PORT-FROM-ENV>/mcp
Click "Connect"

The Inspector allows you to view and test available tools.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "searchcraft" '{"command":"npx","args":["mcp-remote","http://localhost:3100/mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "searchcraft": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://localhost:3100/mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "searchcraft": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://localhost:3100/mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect