onyx-kb-mcp

A Model Context Protocol (MCP) server that provides seamless integration with Onyx AI knowledge bases. Enable any MCP-compatible client (Claude Desktop, Claude Code, Cline, etc.) to search, query, and summarize your organization's knowledge base.


Features

- Semantic Search (search_arq) - Search your Onyx document sets with configurable context retrieval
- Q&A with RAG (ask_arq) - Get comprehensive answers with sources using Onyx's LLM + RAG capabilities
- Executive Summaries (summarize_arq) - Generate concise bullet-point summaries on any topic

Quick Start

$3

- Node.js v16 or higher
- An Onyx instance with API access
- An Onyx API token

$3

``bash
npm install -g onyx-kb-mcp
`

Or use directly with npx (no installation required):

`bash
npx onyx-kb-mcp
`

MCP Client Configuration

$3

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

`json
{
"mcpServers": {
"onyx": {
"command": "npx",
"args": ["-y", "onyx-kb-mcp"],
"env": {
"ONYX_API_TOKEN": "your-api-token-here",
"ONYX_API_URL": "http://localhost:8080/api"
}
}
}
}
`

$3

Add to your Claude Code MCP settings (~/.claude/settings.json):

`json
{
"mcpServers": {
"onyx": {
"command": "npx",
"args": ["-y", "onyx-kb-mcp"],
"env": {
"ONYX_API_TOKEN": "your-api-token-here",
"ONYX_API_URL": "http://localhost:8080/api"
}
}
}
}
`

$3

This server is compatible with Smithery. See smithery.yaml for configuration details.

Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| ONYX_API_TOKEN | Yes | - | Your Onyx API authentication token |
| ONYX_API_URL | No | http://localhost:8080/api | URL of your Onyx API endpoint |
| DEFAULT_PERSONA_ID | No | 0 | Default persona ID for chat interactions |
| DEBUG | No | false | Enable debug logging |

Available Tools

$3

Search your knowledge base for relevant documents with configurable context retrieval.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| query | string | Yes | - | Search query |
| documentSets | string[] | No | all | Document sets to search |
| maxResults | integer | No | 10 | Maximum results (1-20) |
| chunksAbove | integer | No | 1 | Context chunks above match |
| chunksBelow | integer | No | 1 | Context chunks below match |
| retrieveFullDocuments | boolean | No | false | Return full documents |

$3

Ask questions and receive comprehensive answers with source citations.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| query | string | Yes | - | Question to ask |
| personaId | integer | No | 0 | Persona ID to use |
| personaName | string | No | - | Persona name (alternative to ID) |
| documentSets | string[] | No | all | Document sets to search |
| chatSessionId | string | No | - | Session ID for conversation continuity |
| enableAutoDetectFilters | boolean | No | true | Auto-detect search filters |

$3

Generate executive summaries with bullet points and source links.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| topic | string | Yes | - | Topic to summarize |
| maxPoints | integer | No | 5 | Max bullet points (3-10) |

Usage Examples

Once configured, you can use natural language in your MCP client:

`
search arq for authentication documentation

ask arq: how does our deployment process work?

ask arq using "Engineering Assistant": explain the API architecture

summarize arq onboarding process in 5 points
`

Development

`bash


Clone the repository

git clone https://github.com/arqitech/onyx-kb-mcp.git
cd onyx-kb-mcp

Install dependencies

npm install

Build

npm run build

Run in development mode

npm run dev

Run tests

npm test

Lint code

npm run lint
``

License

MIT License - see LICENSE for details.

Author

Arqitech