mcp

# @neuronsearchlab/mcp

MCP (Model Context Protocol) server for [NeuronSearchLab](https://www.neuronsearchlab.com). 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"
"Check my current plan and show which resources are over their limits"
"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](https://registry.modelcontextprotocol.io) 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 plan and usage visibility, 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, billing mutations, and the arbitrary platform API fallback remain available only to trusted local/internal clients so secrets, purchases, and unbounded API calls are not exposed in ChatGPT. Keys minted through OAuth consent appear in [console → Security](https://console.neuronsearchlab.com/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**

```bash
# 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`:

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

**Cursor / Windsurf / other Streamable HTTP clients**

```json
{
  "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

| Tool | Description |
|------|-------------|
| `get_recommendations` | Fetch personalised recommendations for a user |
| `get_auto_recommendations` | Auto-sectioned feed with pagination (infinite scroll) |
| `track_event` | Record a user interaction (click, view, purchase, etc.) |
| `upsert_item` | Add or update a catalogue item |
| `patch_item` | Partially update an item (enable/disable, change fields) |
| `delete_items` | Permanently remove items from the catalogue |
| `search_items` | Search the catalogue by keyword |
| `explain_ranking` | Explain why an item ranked where it did for a user |

## 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:
- account plan and limits: `get_account_plan` returns the effective plan, resolved limits, current usage, and exact overages
- catalogue search and ranking debug: `search_items`, `explain_ranking`
- contexts: `list_contexts`, `create_context`, `update_context`, `delete_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](https://console.neuronsearchlab.com/security).

### 2. Add to Claude Desktop

**Public mode** (recommendations, events, catalogue):

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```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.):

```json
{
  "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.

```text
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:

```text
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:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NSL_PLATFORM_MODE` | No | `public` | `public` or `internal` |
| `NSL_CLIENT_ID` | Public mode | — | OAuth client ID from the console |
| `NSL_CLIENT_SECRET` | Public mode | — | OAuth client secret from the console |
| `NSL_API_KEY` | Internal mode | — | API key with `admin` scope |
| `NSL_TOKEN_URL` | No | `https://auth.neuronsearchlab.com/oauth2/token` | Token endpoint |
| `NSL_API_BASE_URL` | No | `https://api.neuronsearchlab.com` in public mode, `https://console.neuronsearchlab.com` in internal mode | API base URL |
| `NSL_TIMEOUT_MS` | No | `15000` | Request timeout in milliseconds |