@neuronsearchlab/mcp

MCP (Model Context Protocol) server for NeuronSearchLab. Gives any MCP-compatible AI client (Claude, Codex, Cursor, Windsurf, etc.) direct access to NeuronSearchLab recommendations, product/content search, catalogue operations, analytics, and platform controls.

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

Two ways to run it:

• Hosted (recommended, no install): https://console.neuronsearchlab.com/api/mcp — Streamable HTTP with OAuth sign-in or an NSL API key. Listed on the MCP Registry as com.neuronsearchlab/mcp (search neuronsearchlab in the registry API or directory).
• Local stdio via npm: npx -y @neuronsearchlab/mcp in two modes — public (recommendations, events, catalogue via OAuth client credentials) or internal (admin platform via console API key).

Connect to the hosted server (no install)

The hosted endpoint runs a submission-safe customer administration profile. It includes first-class tools for ranking configuration, experiments, training, analytics, catalogue inspection, API-key inventory and revocation, integrations, and event types. Every hosted tool declares its OAuth requirement and requires the authenticated team's admin scope. Credential creation and the arbitrary platform API fallback remain available only to trusted local/internal clients so secrets, billing actions, and unbounded API calls are not exposed in ChatGPT. Keys minted through OAuth consent appear in console → Security and can be revoked there anytime.

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → paste https://console.neuronsearchlab.com/api/mcp → Connect, then sign in to your NeuronSearchLab console and approve the scopes.

Claude Code

# OAuth (browser sign-in):
claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp
# …or with an API key:
claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp \
  --header "Authorization: Bearer nsl_your_key"

OpenAI Codex — in ~/.codex/config.toml:

[mcp_servers.neuronsearchlab]
url = "https://console.neuronsearchlab.com/api/mcp"
bearer_token_env_var = "NSL_API_KEY"

Cursor / Windsurf / other Streamable HTTP clients

{
  "mcpServers": {
    "neuronsearchlab": {
      "url": "https://console.neuronsearchlab.com/api/mcp",
      "headers": { "Authorization": "Bearer nsl_your_key" }
    }
  }
}

Resources

• Product site: https://www.neuronsearchlab.com
• MCP setup guide: https://docs.neuronsearchlab.com/sdk/mcp
• AI agents for recommendation operations: https://www.neuronsearchlab.com/blog/ai-agents-for-recommendation-operations
• Recommendation systems reading path: https://www.neuronsearchlab.com/blog/recommendation-systems

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, refresh_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
• event types: list_event_types, create_event_type, update_event_type, delete_event_type
• credentials and integrations: list_api_keys, revoke_api_key, list_integrations (create_api_key is local/internal only because it returns credential material)
• fallback UI coverage for trusted local/internal clients only: list_platform_routes, call_platform_api

Quickstart (local stdio)

1. Get credentials

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

2. Add to Claude Desktop

Public mode (recommendations, events, catalogue):

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

Internal mode (admin platform — contexts, pipelines, rules, analytics, etc.):

{
  "mcpServers": {
    "neuronsearchlab": {
      "command": "npx",
      "args": ["-y", "@neuronsearchlab/mcp"],
      "env": {
        "NSL_PLATFORM_MODE": "internal",
        "NSL_API_KEY": "your-admin-api-key"
      }
    }
  }
}

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

Try it: recommendation-ops demo

Once connected, run this named demo path before wiring the server into a larger workflow. It proves that an AI client can operate the recommender as an investigation surface rather than just call a recommendation endpoint.

1. List contexts so the assistant confirms the exact surface it is about to inspect.
2. Fetch recommendations for a known test user and context.
3. Search the catalogue for a concrete product/content phrase and compare the returned item IDs with the recommendation set.
4. Explain one ranked item using the request_id from the recommendation or search response when available.
5. Optional, sandbox only: draft or toggle a rule after the explanation shows the expected leak. Keep production contexts read-only unless the operator explicitly approves a write.

Use the NeuronSearchLab MCP server in read-only mode first.
List my recommendation contexts and choose the homepage-feed context.
Get 10 recommendations for user demo-user@example.com using context homepage-feed.
Search the catalogue for waterproof jackets and show the top 5 item ids.
Explain why the first recommended item ranked first, using the request_id from the recommendation response if available.
If you see a relevance leak, draft the smallest rule that would fix it, but do not create or toggle the rule yet.

Internal/admin mode can also inspect operational state before making changes:

List ranking rules for the homepage-feed context.
Show the latest ranking metrics for that context.
Compare item jacket-123 with item jacket-456 and explain which rule or signal separates them.

Next steps after the smoke test:

• create a scoped API key for the client or MCP server
• connect one real recommendation context, such as homepage-feed
• add request attribution to click/view events before judging ranking quality

3. Cursor / other MCP clients

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

npx @neuronsearchlab/mcp

Set NSL_CLIENT_ID + NSL_CLIENT_SECRET for public mode, or NSL_PLATFORM_MODE=internal + NSL_API_KEY for internal mode.

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

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 / enable_rule / disable_rule

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

get_user_analytics

Get served counts, event breakdown, unique-item activity, and click-through rate for a specific user.

Inputs

get_item_analytics

Get served counts, event breakdown, watch/click counts, and click-through rate for a specific item.

Inputs

compare_items

Compare two items head-to-head by served count, events, clicks, and CTR over the same time window.

Inputs

top_items

List the top items by served count or by matching event activity over a time window. Use metric="served" for generic "top item" or "best performing" questions. Use metric="events" when the user explicitly names an engagement signal (e.g. watch, click, purchase).

Inputs

Example

What's the top item served in the last 7 days?
Which items had the most watch events last month?

Authentication

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

Internal mode uses a NeuronSearchLab API key with the admin scope. Set NSL_API_KEY and NSL_PLATFORM_MODE=internal.

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