Skip to main content
The NeuronSearchLab MCP server lets you use your recommendation engine from any MCP-compatible AI client. Ask questions, manage your catalog, debug rankings, and run experiments through natural language conversation.

​
Installation

The MCP server is published as an npm package. No local installation is required — your MCP client runs it automatically via npx.

​
Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json): 
{
  "mcpServers": {
    "neuronsearchlab": {
      "command": "npx",
      "args": ["-y", "@neuronsearchlab/mcp"],
      "env": {
        "NSL_CLIENT_ID": "your-client-id",
        "NSL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

​
Cursor / Windsurf

Add the same configuration to your editor’s MCP settings. The server uses stdio transport and works with any MCP-compatible client.

​
Claude Code

claude mcp add neuronsearchlab -- npx -y @neuronsearchlab/mcp \
  --env NSL_CLIENT_ID=your-client-id \
  --env NSL_CLIENT_SECRET=your-client-secret

​
Configuration

All configuration is done through environment variables:
VariableRequiredDefaultDescription
NSL_CLIENT_IDYes (public mode)—OAuth 2.0 client ID from Console > SDK Credentials
NSL_CLIENT_SECRETYes (public mode)—OAuth 2.0 client secret
NSL_PLATFORM_MODENopublicpublic or internal
NSL_API_KEYYes (internal mode)—API key with admin scope
NSL_TIMEOUT_MSNo15000Request timeout in milliseconds

​
Public mode (default)

Uses OAuth 2.0 client credentials to authenticate against the public API (api.neuronsearchlab.com). This mode provides access to recommendations, catalog management, events, segments, experiments, campaigns, and analytics.

​
Internal mode

Uses a static API key to authenticate against the console API (console.neuronsearchlab.com). This mode provides access to context, pipeline, and rule management — the same admin operations available in the console. 
{
  "mcpServers": {
    "neuronsearchlab": {
      "command": "npx",
      "args": ["-y", "@neuronsearchlab/mcp"],
      "env": {
        "NSL_PLATFORM_MODE": "internal",
        "NSL_API_KEY": "nsl_your_api_key"
      }
    }
  }
}

​
Available tools

​
Recommendations and catalog (public mode)

ToolDescription
get_recommendationsFetch personalised recommendations for a user
get_auto_recommendationsPaginated auto-generated sections for infinite-scroll feeds
explain_rankingDebug why an item ranked at a given position
search_itemsSearch your catalog by keyword
upsert_itemAdd or update a catalog item
patch_itemPartially update an item (e.g. enable/disable)
delete_itemsPermanently remove items
track_eventRecord a user interaction event

​
Segments (public mode)

ToolDescription
list_segmentsList all user segments
get_segmentGet segment definition
create_segmentCreate a user segment
update_segmentModify a segment
delete_segmentRemove a segment
get_segment_statsGet segment size and overlap stats

​
Experiments (public mode)

ToolDescription
list_experimentsList all A/B experiments
get_experimentGet experiment details
create_experimentCreate an A/B test with variants
update_experimentModify an experiment
start_experimentBegin traffic splitting
stop_experimentEnd an experiment
get_experiment_resultsGet statistical results

​
Campaigns (public mode)

ToolDescription
list_campaignsList all campaigns
create_campaignCreate a time-bound campaign
activate_campaignEnable a campaign
pause_campaignPause a campaign
delete_campaignRemove a campaign

​
Analytics (public mode)

ToolDescription
get_ranking_metricsGet ranking performance metrics
get_experiment_metricsGet live experiment stats
get_segment_metricsGet segment performance

​
Admin tools (internal mode)

ToolDescription
list_contexts / create_context / update_context / delete_contextManage recommendation contexts
list_pipelines / create_pipeline / activate_pipeline / clone_pipelineManage ranking pipelines
list_rules / create_rule / toggle_rule / delete_ruleManage ranking rules

​
Example conversations

​
Get recommendations

“Get 5 recommendations for user alice@example.com in the homepage context”
The assistant calls get_recommendations and returns the ranked items with scores and metadata.

​
Debug a ranking

“Why did item prod-456 rank so low for user alice?”
The assistant calls explain_ranking and shows the score breakdown, which rules matched, and how each pipeline stage affected the result.

​
Create a rule

“Create a boost rule that promotes items in the Electronics category with a 2x weight”
The assistant calls create_rule with the appropriate conditions and actions.

​
Track an event

“Record that alice clicked on item prod-456”
The assistant calls track_event with the user ID, item ID, and event type.

​
Error handling

The MCP server includes automatic retry with exponential backoff for transient errors (429, 5xx, timeouts). All tool responses are formatted as human-readable text so the AI assistant can interpret and relay results clearly.

​
Next steps