Operator reference

Nexus MCP Server

Connect LLMs like Claude, Cursor, and other AI tools to your Nexus knowledge base via the Model Context Protocol

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls.

Overview#

The Nexus MCP Server lets any MCP-compatible LLM client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) access your Nexus knowledge base, web search, and URL fetching capabilities through the Model Context Protocol.

Prerequisites#

Before connecting, you'll need:

A running Nexus instance (either self-hosted or a managed deployment)
Authentication. see Personal Access Tokens or API Keys
An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

Self-Hosted MCP Server Configuration #

Jump to environment variables, networking, and deployment settings for self-hosted MCP server

Quick Start#

Claude Code (CLI)#

claude mcp add --transport http onyx https://school.narb.cc/mcp \
--header "Authorization: Bearer YOUR_ONYX_TOKEN_HERE"

Or add it to your project's .mcp.json:

{
"mcpServers": {
  "onyx": {
    "type": "http",
    "url": "https://school.narb.cc/mcp",
    "headers": {
      "Authorization": "Bearer ${ONYX_TOKEN}"
    }
  }
}
}

Then set the environment variable before running Claude Code:

export ONYX_TOKEN="your-token-here"
claude

Claude Desktop#

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
  "onyx": {
    "url": "https://school.narb.cc/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_ONYX_TOKEN_HERE"
    }
  }
}
}

Replace https://school.narb.cc/mcp with http://YOUR_ONYX_DOMAIN:8090/ if you're self-hosting.

Cursor / Windsurf / Other MCP Clients#

Most MCP clients support HTTP transport with custom headers. The connection details are:

Setting	Value
URL	`https://school.narb.cc/mcp` (or `http://YOUR_DOMAIN:8090/`)
Transport	HTTP (Streamable HTTP)
Auth Header	`Authorization: Bearer YOUR_TOKEN`

Refer to your client's MCP documentation for exact configuration steps.

Available Tools#

The MCP server exposes three tools that LLM clients can invoke:

search_indexed_documents#

Search your private knowledge base indexed in Nexus. Returns ranked document chunks with content, relevance scores, and metadata.

Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	.	Natural language search query
`source_types`	string[]	No	All sources	Filter by connector type (e.g. `["confluence", "github", "jira"]`)
`time_cutoff`	string	No	No cutoff	ISO 8601 datetime. only return docs updated after this time
`limit`	integer	No	`10`	Maximum number of results to return

Example call:

  {
    "query": "What is the latest status of PROJ-1234?",
    "source_types": ["jira", "google_drive"],
    "time_cutoff": "2025-01-01T00:00:00Z",
    "limit": 5
  }

Response fields:

Field	Description
`documents`	Array of result objects
`documents[].semantic_identifier`	Human-readable document name
`documents[].content`	Relevant text snippet
`documents[].source_type`	Connector source (e.g. `"confluence"`)
`documents[].link`	URL to the original document
`documents[].score`	Relevance score
`total_results`	Number of results returned
`query`	The original query
`executed_queries`	List of queries actually executed (may include expansions)

To discover which source types are available, use the indexed_sources resource (see below).

search_web#

Search the public internet for general knowledge and current events.

Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search query
`limit`	integer	No	`5`	Maximum number of results

Example call:

  {
    "query": "React 19 migration guide",
    "limit": 5
  }

Response fields:

Field	Description
`results`	Array of web search results
`results[].title`	Page title
`results[].url`	Page URL
`results[].snippet`	Short text excerpt
`query`	The original query

search_web returns snippets, not full page content. Use open_urls to fetch the complete text of any result.

open_urls#

Retrieve the complete text content from one or more web URLs.

Parameters:

Parameter	Type	Required	Description
`urls`	string[]	Yes	List of URLs to fetch

Example call:

  {
    "urls": [
      "https://react.dev/blog/2024/12/05/react-19",
      "https://react.dev/learn/react-compiler"
    ]
  }

Response fields:

Field	Description
`results`	Array of fetched pages
`results[].title`	Page title
`results[].url`	The fetched URL
`results[].content`	Full extracted text content

Available Resources#

indexed_sources#

URI: resource://indexed_sources

Lists all document connector types currently indexed in your Onyx instance (e.g. "confluence", "github", "google_drive", "slack").

Use this to discover valid values for the source_types filter in search_indexed_documents.

Example response:

  {
    "indexed_sources": ["confluence", "github", "google_drive", "jira", "slack"]
  }

Self-Hosted Configuration#

To self-host the MCP server, you will need to enable the deployment via environment variables.

Docker:

MCP_SERVER_ENABLED=true

Kubernetes:

configMap:
MCP_SERVER_ENABLED: "true"

Health Check#

Verify the MCP server is running:

curl http://localhost:8090/health # or http://YOUR_DOMAIN:8090/health

Expected response:

{
"status": "healthy",
"service": "mcp_server"
}

Environment Variables#

Most users should not need to configure these environment variables.

Variable	Default	Description
`MCP_SERVER_ENABLED`	`false`	Set to `"true"` to enable the MCP server
`MCP_SERVER_HOST`	`0.0.0.0`	Host to bind the MCP server
`MCP_SERVER_PORT`	`8090`	Port for the MCP server
`MCP_SERVER_CORS_ORIGINS`	(empty)	Comma-separated list of allowed CORS origins
`API_SERVER_PROTOCOL`	`http`	Protocol for internal API server connection
`API_SERVER_HOST`	`127.0.0.1`	Hostname for internal API server connection
`API_SERVER_URL_OVERRIDE_FOR_HTTP_REQUESTS`	(unset)	Full URL override for API server. Use this when self-hosting the MCP server against Onyx Cloud