Mcp MCP Server

@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.
• 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 the full platform toolset; what a connection can actually do is governed by the scopes of the API key behind it (an admin-scoped key unlocks everything). 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
• 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, create_api_key, revoke_api_key, list_integrations
• fallback UI coverage: 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

Once connected, use this short demo path to prove the server is useful before wiring it into a larger workflow:

1. Fetch recommendations for a known user and context.
2. Search the catalogue for a concrete product phrase.
3. Record a click event against one returned item, including the response request_id when available.
4. Ask for a ranking explanation on the clicked item.

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

For internal mode, keep the first pass read-only:

List my recommendation contexts
Show the latest ranking metrics
Compare item jacket-123 with item jacket-456

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