ChatGPT plugin and MCP

The NeuronSearchLab plugin lets you use your recommendation engine from ChatGPT. Ask questions, manage your catalogue, debug rankings, and run experiments through natural language conversation. The same capabilities are also available to other MCP-compatible clients through the hosted endpoint.

ChatGPT

Open the ChatGPT plugin directory and install NeuronSearchLab.
Start a ChatGPT conversation with the NeuronSearchLab plugin enabled.
When ChatGPT asks you to connect your account, select Connect.
Sign up for NeuronSearchLab or log in to the NeuronSearchLab console.
Approve access. The authorization flow returns you to ChatGPT with the plugin connected to your workspace.

ChatGPT customers do not need to enable Developer mode, enter an MCP URL, create an API key, install an npm package, or run an MCP server locally. Those options are only for developers testing an unpublished plugin or connecting a different MCP client.

OpenAI publishes reviewed plugins through its universal plugin directory. See the official OpenAI plugin overview for the distinction between installing a published plugin and building or testing one.

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. For clients other than ChatGPT, there are two ways to connect:

Hosted (recommended) - point your client at https://console.neuronsearchlab.com/api/mcp. Nothing to install; sign in with OAuth or pass an API key. Listed on the official MCP Registry as com.neuronsearchlab/mcp (search neuronsearchlab in the registry API or directory).
Local (stdio) - run npx -y @neuronsearchlab/mcp from your client, configured with environment variables.

Connect another MCP client

The hosted endpoint exposes a submission-safe customer administration profile. Its 53 tools cover account plan and usage visibility, recommendations, catalogue inspection, contexts, pipelines, rules, segments, experiments, campaigns, training, analytics, integrations, and event types. Every hosted tool requires the authenticated team’s admin scope. Credential creation, billing changes, and the arbitrary Platform API fallback are intentionally unavailable through the hosted endpoint. OAuth-created keys are named Connector: <client> and can be revoked at any time from Console > Security.

claude.ai / Claude Desktop
Claude Code
OpenAI Codex
Cursor / Windsurf

Open Settings → Connectors → Add custom connector.
Paste https://console.neuronsearchlab.com/api/mcp and click Add.
Click Connect - you’ll be taken to your NeuronSearchLab console to sign in and approve the permission scopes.

That’s it: no npm, no config file, no copied keys.

OAuth (browser sign-in):

claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp

Or with an API key from Console > Security:

claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp \
  --header "Authorization: Bearer nsl_your_key"

Add --scope project to share the server with your team via a checked-in .mcp.json.

In ~/.codex/config.toml:

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

Then export NSL_API_KEY=nsl_your_key in your shell. You can also use codex mcp add neuronsearchlab --url https://console.neuronsearchlab.com/api/mcp.

Add to your editor’s MCP settings (.cursor/mcp.json or equivalent):

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

The endpoint implements Streamable HTTP with OAuth 2.1 discovery based on RFC 8414 and RFC 9728, so compatible remote MCP clients can connect with OAuth or bearer headers.

Local installation (stdio)

This section is for developers using an MCP client that requires a local stdio process. It is not part of the ChatGPT plugin setup. For air-gapped environments, custom base URLs, or local MCP development, the server is published as @neuronsearchlab/mcp and your client runs it automatically through 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"
      }
    }
  }
}

Claude Code

claude mcp add neuronsearchlab -- npx -y @neuronsearchlab/mcp \
  --env NSL_CLIENT_ID=your-client-id \
  --env NSL_CLIENT_SECRET=your-client-secret

Recommendation-ops demo path

After connecting the published ChatGPT plugin or another MCP client, run the smallest end-to-end loop before adding custom prompts or automations. Keep the first pass read-only so the assistant can investigate ranking behavior without mutating a production surface.

List contexts and confirm the exact context/surface to inspect.
Fetch recommendations for a test user and selected context.
Search the catalog for a concrete product/content phrase and compare result IDs.
Explain one ranked item with the request_id from the recommendation/search response when available.
Optional, sandbox only: draft or toggle a rule after the explanation shows the expected leak.

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

For internal/admin mode, inspect operational state before proposing a change:

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.

This is the buyer-facing story: ChatGPT audits a recommendation surface, explains the leak, and drafts the fix. Operators stay in control because destructive MCP tools carry annotations and the safe demo prompt explicitly asks for a draft before any rule write.

Configuration

All local 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 against the Core API. It supports recommendations, events, and catalogue operations. Internal mode uses a static admin API key against the console API. It exposes the platform administration tools plus three trusted-client tools that are not available on the hosted endpoint: create_api_key, list_platform_routes, and call_platform_api.

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

Available tools

The sections below show the combined tool surface. Core API mode supports recommendation, event, and catalogue tools. Hosted and internal modes support the platform administration tools. Every tool carries MCP annotations (readOnlyHint and destructiveHint) so compatible clients can distinguish read-only operations from writes.

Recommendations and catalog

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

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

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

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

Tool	Description
`get_ranking_metrics`	Get ranking performance metrics
`get_experiment_metrics`	Get live experiment stats
`get_segment_metrics`	Get segment performance
`get_user_analytics`	Per-user engagement analytics
`get_item_analytics`	Per-item performance analytics
`compare_items`	Side-by-side item comparison
`top_items`	Top items by metric

Platform administration

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
`list_event_types` / `create_event_type` / `update_event_type` / `delete_event_type`	Manage event type definitions
`get_account_plan`	Show the effective plan, resolved limits, current usage, and exact overages
`list_training_jobs` / `get_training_job` / `create_training_job` / `cancel_training_job`	Manage model training jobs
`list_api_keys` / `revoke_api_key`	Inspect and revoke API credentials
`list_integrations`	Inspect configured integrations
`create_api_key`	Create an API credential in trusted local internal mode only
`list_platform_routes` / `call_platform_api`	Trusted local internal fallback for console capabilities without a dedicated tool

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

Create an API key or SDK credentials in Console > Security.
Find the server on the MCP Registry as com.neuronsearchlab/mcp.
Try the built-in NeuronSearchLab AI assistant in the console - it uses the same MCP tools.
View the JavaScript SDK for direct programmatic access.

JavaScript SDK

PHP SDK

MCP Integration

ChatGPT

AI agents for recommendation operations

Connect another MCP client

Local installation (stdio)

Claude Desktop

Claude Code

Recommendation-ops demo path

Configuration

Available tools

Recommendations and catalog

Segments

Experiments

Campaigns

Analytics

Platform administration

Example conversations

Get recommendations

Debug a ranking

Create a rule

Track an event

Error handling

Next steps

​ChatGPT

​AI agents for recommendation operations

​Connect another MCP client

​Local installation (stdio)

​Claude Desktop

​Claude Code

​Recommendation-ops demo path

​Configuration

​Available tools

​Recommendations and catalog

​Segments

​Experiments

​Campaigns

​Analytics

​Platform administration

​Example conversations

​Get recommendations

​Debug a ranking

​Create a rule

​Track an event

​Error handling

​Next steps

ChatGPT

AI agents for recommendation operations

Connect another MCP client

Local installation (stdio)

Claude Desktop

Claude Code

Recommendation-ops demo path

Configuration

Available tools

Recommendations and catalog

Segments

Experiments

Campaigns

Analytics

Platform administration

Example conversations

Get recommendations

Debug a ranking

Create a rule

Track an event

Error handling

Next steps