@neuronsearchlab/mcp

MCP (Model Context Protocol) server for NeuronSearchLab. Gives any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) direct access to NeuronSearchLab in two modes:

• public: recommendations, events, and catalogue operations via OAuth client credentials

• internal: internal admin-platform operations via console API key auth

"Get 5 recommendations for user alice@example.com"
"Create a new context called Twitter Feed"
"Add a pin rule so Nike items always appear in the top 3"
"Why did item prod-456 rank first for bob?"

Tools

API tools

Modes

Public mode

Uses OAuth client credentials and the public API.

Supported:

• recommendations

• events

• catalogue operations

Internal mode

Uses a NeuronSearchLab API key with the admin scope against the console API.

Currently supported:

• catalogue search and ranking debug: search_items, explain_ranking

• contexts: list_contexts, create_context, update_context, get_context

• pipelines: list_pipelines, create_pipeline, update_pipeline, delete_pipeline, activate_pipeline, deactivate_pipeline, clone_pipeline, get_pipeline

• rules: list_rules, create_rule, update_rule, delete_rule, toggle_rule, enable_rule, disable_rule, get_rule

• segments: list_segments, get_segment, create_segment, update_segment, delete_segment

• experiments: list_experiments, get_experiment, create_experiment, update_experiment, start_experiment, stop_experiment, get_experiment_results

• training: list_training_jobs, get_training_job, create_training_job, cancel_training_job

• analytics: get_ranking_metrics, get_user_analytics, get_item_analytics, compare_items, top_items

• credentials and integrations: list_api_keys, create_api_key, revoke_api_key, list_integrations

• fallback UI coverage: list_platform_routes, call_platform_api

Quickstart

1. Get credentials

Generate SDK Credentials (OAuth 2.0 client ID + secret) from the NeuronSearchLab console.

2. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/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"
      }
    }
  }
}

Restart Claude Desktop. You'll see a 🔌 neuronsearchlab indicator in the toolbar when it's connected.

3. Cursor / other MCP clients

Follow your client's MCP server guide. The command is:

npx @neuronsearchlab/mcp

Set env vars NSL_CLIENT_ID and NSL_CLIENT_SECRET.

Releases

This repo uses Changesets plus GitHub Actions for automated versioning and npm publishing.

• Add a changeset for any user-facing package change with npm run changeset

• Merge that PR into main

• The release.yml workflow opens or updates a version PR

• Merging the version PR publishes @neuronsearchlab/mcp to npm automatically

To enable trusted publishing, configure the package on npmjs.com to trust the release.yml workflow in this repository.

Configuration

All configuration is via environment variables:

Tool reference

get_recommendations

Fetch personalised recommendations for a user. Returns ranked items with scores and a request_id for attribution.

Inputs

Example

Get 10 recommendations for user alice@example.com using context homepage-feed

get_auto_recommendations

Fetch the next auto-generated section for a user's feed. Designed for infinite-scroll — each call returns one curated section (e.g. "Trending this week", "New for you") plus a cursor for the next section. Call until done: true.

Inputs

track_event

Record a user interaction. Always pass request_id from the recommendations response to enable click-through attribution.

Inputs

upsert_item

Add or update an item in the catalogue. The description field is used to generate the embedding — write it to be rich and descriptive.

Inputs

patch_item

Partially update an existing catalogue item.

Inputs

delete_items

Permanently remove items. Cannot be undone. To temporarily exclude, use patch_item with active: false.

Inputs

search_items

Search the catalogue by keyword.

Inputs

explain_ranking

Explain why a specific item was ranked at a given position for a user. Returns score breakdown, applied rules, and pipeline trace.

Inputs

list_contexts

List all recommendation contexts (feeds) configured for your team.

Inputs — none

create_context

Create a new recommendation context.

Inputs

Example

Create a new context called "Twitter Feed" with type homepage_feed

update_context

Update an existing context.

Inputs

delete_context

Delete a context and its associated pipelines and rules.

Inputs

list_pipelines

List all ranking pipelines.

Inputs — none

create_pipeline

Create a new ranking pipeline with default stages.

Inputs

update_pipeline / delete_pipeline

Update or delete a pipeline by pipeline_id.

list_rules

List ranking rules, optionally filtered by context_id.

create_rule

Create a ranking rule. Rule types:

Inputs

Example

Create a pin rule called "Pin Nike" that pins items where brand equals "Nike" to position 3, scoped to context 1

update_rule / delete_rule / toggle_rule

Update, delete, or enable/disable a rule by rule_id.

Authentication

The server uses OAuth 2.0 Client Credentials. Tokens are fetched on startup, cached in memory, and auto-refreshed 60 seconds before expiry.

Development

git clone https://github.com/NeuronSearchLab/mcp
cd mcp
npm install
export NSL_CLIENT_ID=your-client-id
export NSL_CLIENT_SECRET=your-client-secret
npm run dev           # dev mode (tsx, no build)
npm run build         # compile to dist/

License

MIT