Onyx

You can connect MCP-compatible clients to your Onyx knowledge base with this Onyx MCP Server. It enables semantic search across documents, contextual chunk retrieval, full document access, and chat-style answers via Onyx’ API, giving your team fast, relevant context during searches or conversations.

How to use

You will run the Onyx MCP Server locally and connect it to your MCP client. Use the provided tools to perform targeted searches and to chat with Onyx for synthesized answers. Start by ensuring your Onyx instance is accessible and you have a valid API token. Once the server is running, point your MCP client at the local server configuration and select either the Search or Chat tool to retrieve context or get comprehensive answers across your document sets.

How to install

Prerequisites: Node.js version 16 or higher, an Onyx instance with API access, and an Onyx API token.

Step 1. Clone the project directory.

git clone https://github.com/lupuletic/onyx-mcp-server.git
cd onyx-mcp-server

Step 2. Install dependencies.

npm install

Step 3. Build the server.

npm run build

Step 4. Configure your Onyx API token and URL.

export ONYX_API_TOKEN="your-api-token-here"
export ONYX_API_URL="http://localhost:8080/api"  # Adjust as needed

Step 5. Start the server.

npm start

Configuration snippets for MCP clients

You can configure MCP clients to load the server. Below are example configurations for Claude Desktop and Claude in VSCode (Cline). These show how to point your client at the local server and supply the required environment variables.

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false, 
      "alwaysAllow": []
    }
  }
}

Notes and security

Keep your Onyx API token secure and set the environment variables in your client configuration or shell session where the server runs. If your Onyx instance requires a different API URL, adjust ONYX_API_URL accordingly.

Available tools

search_onyx

Tool to perform semantic search across Onyx documents with enhanced context retrieval. Returns relevant chunks and optional full documents based on configuration.

chat_with_onyx

Tool to query Onyx chat API with LLM + RAG, enabling synthesized answers from multiple document sources and maintained chat context.