MCP Integration - NeuronSearchLab

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.

AI agents for recommendation operations

A useful recommendation agent should be able to complete a small operational loop: fetch recommendations, search the catalogue, record a feedback event with request attribution, and explain why an item ranked where it did. That turns the assistant from a passive chatbot into an operator-facing tool for relevance investigations. Use the AI agents for recommendation operations article as the public framing, then run the demo path below to verify the MCP server against one real context.

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

Demo path

After connection, run the smallest end-to-end loop before adding custom prompts or automations:

Ask for recommendations for a test user and context.
Search the catalog for a concrete product phrase.
Record a click or view event for one returned item, including the event type ID and the response request_id when available.
Ask why that item ranked where it did.

Get 10 recommendations for user demo-user@example.com using context homepage-feed
Search the catalog for waterproof jackets and show the top 5 item ids
Record event type id 1 as a click for item jacket-123 from user demo-user@example.com, using the request_id from the recommendation or search response
Explain why item jacket-123 ranked first for demo-user@example.com

Configuration

All configuration is done through environment variables:

Variable	Required	Default	Description
`NSL_CLIENT_ID`	Yes (Core API mode)	—	OAuth 2.0 client ID from Console > SDK Credentials
`NSL_CLIENT_SECRET`	Yes (Core API mode)	—	OAuth 2.0 client secret
`NSL_PLATFORM_MODE`	No	`public`	`public` or `internal`
`NSL_API_KEY`	Yes (internal mode)	—	API key with admin scope
`NSL_TIMEOUT_MS`	No	`15000`	Request timeout in milliseconds

Core API mode (default, `public`)

Uses OAuth 2.0 client credentials to authenticate against the Core API. 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 (Core API mode)

Tool	Description
`get_recommendations`	Fetch personalised recommendations for a user
`get_auto_recommendations`	Paginated auto-generated sections for infinite-scroll feeds
`explain_ranking`	Debug why an item ranked at a given position
`search_items`	Search your catalog by keyword
`upsert_item`	Add or update a catalog item
`patch_item`	Partially update an item (e.g. enable/disable)
`delete_items`	Permanently remove items
`track_event`	Record a user interaction event

Segments (Core API mode)

Tool	Description
`list_segments`	List all user segments
`get_segment`	Get segment definition
`create_segment`	Create a user segment
`update_segment`	Modify a segment
`delete_segment`	Remove a segment
`get_segment_stats`	Get segment size and overlap stats

Experiments (Core API mode)

Tool	Description
`list_experiments`	List all A/B experiments
`get_experiment`	Get experiment details
`create_experiment`	Create an A/B test with variants
`update_experiment`	Modify an experiment
`start_experiment`	Begin traffic splitting
`stop_experiment`	End an experiment
`get_experiment_results`	Get statistical results

Campaigns (Core API mode)

Tool	Description
`list_campaigns`	List all campaigns
`create_campaign`	Create a time-bound campaign
`activate_campaign`	Enable a campaign
`pause_campaign`	Pause a campaign
`delete_campaign`	Remove a campaign

Analytics (Core API mode)

Tool	Description
`get_ranking_metrics`	Get ranking performance metrics
`get_experiment_metrics`	Get live experiment stats
`get_segment_metrics`	Get segment performance

Admin tools (internal mode)

Tool	Description
`list_contexts` / `create_context` / `update_context` / `delete_context`	Manage recommendation contexts
`list_pipelines` / `create_pipeline` / `activate_pipeline` / `clone_pipeline`	Manage ranking pipelines
`list_rules` / `create_rule` / `toggle_rule` / `delete_rule`	Manage 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

Get your SDK credentials from Console > SDK Credentials.
Try the built-in NeuronSearchLab AI assistant in the console — it uses the same MCP tools.
View the JavaScript SDK for direct programmatic access.

​AI agents for recommendation operations

​Installation

​Claude Desktop

​Cursor / Windsurf

​Claude Code

​Demo path

​Configuration

​Core API mode (default, public)

​Internal mode

​Available tools

​Recommendations and catalog (Core API mode)

​Segments (Core API mode)

​Experiments (Core API mode)

​Campaigns (Core API mode)

​Analytics (Core API mode)

​Admin tools (internal mode)

​Example conversations

​Get recommendations

​Debug a ranking

​Create a rule

​Track an event

​Error handling

​Next steps