onyx

Onyx MCP Server exposes two tools to integrate Onyx knowledge bases with MCP clients: a search tool and a chat tool. After you configure the server in your MCP client, you can use the search tool to perform semantic searches across your Onyx document sets with context retrieval options, such as including chunks above or below the match and choosing whether to fetch full documents. The chat tool leverages Onyx's chat API with LLM + RAG to generate synthesized answers across multiple sources. Use search for targeted facts and document-level context, and use chat for comprehensive, synthesized responses that combine information from multiple documents. The server expects standard MCP tool invocation patterns, where you specify the server name (e.g., onyx-search) and the tool name (search_onyx or chat_with_onyx) along with a JSON payload of options like query, documentSets, and retrieval preferences.

Prerequisites:

• Node.js v16 or higher
• npm (comes with Node.js)
• An Onyx instance with API access and a valid API token

Step-by-step installation:

1. Clone the repository and install dependencies git clone https://github.com/lupuletic/onyx-mcp-server.git cd onyx-mcp-server npm install

2. Build the server npm run build

3. Configure your Onyx API token and URL (example, in your shell or environment file) export ONYX_API_TOKEN="your-api-token-here" export ONYX_API_URL="http://localhost:8080/api" # adjust as needed

4. Run the server npm start

Optional: Install via Smithery for Claude Desktop integration as shown in the repository README: npx -y @smithery/cli install @lupuletic/onyx-mcp-server --client claude

Note: If you need to customize the MCP client configuration, you can add a server entry under mcpServers with the command set to node and the path to the built index.js, along with the required ONYX_API_TOKEN and ONYX_API_URL environment variables.

Environment variables can be critical for connecting to Onyx. Ensure ONYX_API_TOKEN and ONYX_API_URL are kept secure and not checked into version control. When deploying, you may want to pin Node.js to a compatible version (e.g., use nvm to manage versions). If you encounter connectivity issues, verify that ONYX_API_URL is reachable from your server host and that the Onyx instance accepts the provided token. The MCP server supports two tools: search_onyx for targeted retrieval with context, and chat_with_onyx for comprehensive, multi-source synthesis. You can configure multiple MCP clients to point at the same server if needed, using different documentSets or personas as appropriate.