模型上下文协议 (MCP) 服务器可与 Onyx AI 知识库无缝集成。
此 MCP 服务器可将任何兼容 MCP 的客户端连接到您的 Onyx 知识库，让您能够搜索并检索文档中的相关上下文。它为 MCP 客户端和 Onyx API 之间搭建了桥梁，从而实现强大的语义搜索和聊天功能。
增强搜索：使用 LLM 相关性过滤功能对 Onyx 文档集进行语义搜索
上下文窗口检索：检索匹配块上方和下方的块以获得更好的上下文
完整文档检索：可以选择检索整个文档，而不是只检索部分文档
聊天集成：使用 Onyx 强大的聊天 API 与 LLM + RAG 获得全面的答案
可配置文档集过滤：针对特定文档集获取更相关的结果
Related MCP server: atlas_mcp
要通过Smithery自动为 Claude Desktop 安装 Onyx MCP Server：
npx -y @smithery/cli install @lupuletic/onyx-mcp-server --client claudeNode.js（v16 或更高版本）
具有 API 访问权限的 Onyx 实例
Onyx API 令牌
克隆存储库：
git clone https://github.com/lupuletic/onyx-mcp-server.git
cd onyx-mcp-server安装依赖项：
npm install构建服务器：
npm run build配置您的 Onyx API 令牌：
export ONYX_API_TOKEN="your-api-token-here"
export ONYX_API_URL="http://localhost:8080/api" # Adjust as needed启动服务器：
npm start添加到~/Library/Application Support/Claude/claude_desktop_config.json ：
{
"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": []
}
}
}添加到您的 Cline MCP 设置文件：
{
"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": []
}
}
}请参阅您的 MCP 客户端文档，了解如何添加自定义 MCP 服务器。您需要提供：
运行服务器的命令（ node ）
构建服务器文件的路径（ /path/to/onyx-mcp-server/build/index.js ）
ONYX_API_TOKEN和ONYX_API_URL的环境变量
配置完成后，您的 MCP 客户端将可以使用两个强大的工具：
search_onyx工具可以直接访问 Onyx 的搜索功能，并具有增强的上下文检索功能：
<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>search_onyx</tool_name>
<arguments>
{
"query": "customer onboarding process",
"documentSets": ["Company Policies", "Training Materials"],
"maxResults": 3,
"chunksAbove": 1,
"chunksBelow": 1,
"retrieveFullDocuments": true
}
</arguments>
</use_mcp_tool>参数：
query （必填）：要搜索的主题
documentSets （可选）：要搜索的文档集名称列表（全部为空）
maxResults （可选）：返回的最大结果数（默认值：5，最大值：10）
chunksAbove （可选）：匹配块上方包含的块数（默认值：1）
chunksBelow （可选）：匹配块下方包含的块数（默认值：1）
retrieveFullDocuments （可选）：是否检索完整文档而不仅仅是块（默认值：false）
chat_with_onyx工具利用 Onyx 强大的聊天 API 与 LLM + RAG 来提供全面的答案：
<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>chat_with_onyx</tool_name>
<arguments>
{
"query": "What is our company's policy on remote work?",
"personaId": 15,
"documentSets": ["Company Policies", "HR Documents"],
"chatSessionId": "optional-existing-session-id"
}
</arguments>
</use_mcp_tool>参数：
query （必填）：向 Onyx 询问的问题
personaId （可选）：要使用的角色的 ID（默认值：15）
documentSets （可选）：要搜索的文档集名称列表（全部为空）
chatSessionId （可选）：用于继续对话的现有聊天会话 ID
聊天工具支持在多次交互中维护对话上下文。首次调用后，响应将在元数据中包含一个chat_session_id 。您可以在后续调用中传递此 ID 来维护上下文。
使用搜索的情况：您需要从文档中获取特定的、有针对性的信息，并希望精确控制检索到的上下文量。
使用聊天的情况：您需要结合来自多个来源的信息的综合答案，或者当您希望 LLM 为您综合信息时。
为了获得最佳效果，您可以结合使用这两种工具 - 搜索具体细节并通过聊天获得全面了解。
知识管理：通过任何与 MCP 兼容的界面访问您组织的知识库
客户支持：帮助支持代理快速找到相关信息
研究：对组织内的文档进行深入研究
培训：提供培训材料和文档
政策合规性：确保团队能够了解最新的政策和程序
npm run dev本项目强制所有提交信息遵循约定式提交规范。为了方便使用，我们提供了一个交互式提交工具：
npm run commit这将指导您创建格式正确的提交消息。或者，您可以按照常规格式编写自己的提交消息：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]其中type为以下之一：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert
npm run build运行测试套件：
npm test运行覆盖测试：
npm run test:coveragenpm run lint修复 linting 问题：
npm run lint:fix该项目使用 GitHub Actions 进行持续集成和部署。CI 流水线会在每次推送到主分支以及拉取请求时运行。它会执行以下检查：
代码检查
建筑
测试
代码覆盖率报告
当 PR 合并到主分支时，项目会自动确定合适的版本升级类型并发布到 npm。系统会分析 PR 标题和提交信息来确定版本升级类型。
PR 标题验证：所有 PR 标题均根据常规提交规范进行验证：
PR 标题必须以类型开头（例如feat: 、 fix: 、 docs: ）
创建或更新 PR 时会自动进行此验证
标题无效的 PR 将无法通过验证检查
提交消息验证：所有提交消息也都根据常规提交格式进行验证：
提交消息必须以类型开头（例如， feat: 、 fix: 、 docs: ）
这是由提交时运行的 git hooks 强制执行的
包含无效信息的提交将被拒绝
使用npm run commit作为交互式提交消息创建工具
版本升级确定：系统分析 PR 标题和提交消息以确定适当的版本升级：
PR 标题以feat开头或包含新功能 → 小版本升级
PR 标题以fix开头或包含错误修复 → patch 版本升级
PR 标题包含BREAKING CHANGE或感叹号 → 主要版本升级
如果 PR 标题未指明具体的 bump 类型，系统会分析提交消息
使用在任何提交消息中找到的最高优先级的 bump 类型（主要 > 次要 > 补丁）
如果没有找到常规提交前缀，系统将自动默认使用补丁版本升级，而不会失败
版本更新与发布：
根据语义版本控制来调整 package.json 中的版本
提交并推送版本变更
将新版本发布到 npm
此自动化过程可确保根据变化的性质进行一致的版本控制，遵循语义版本控制原则，并消除手动版本管理。
欢迎贡献！更多详情请参阅我们的贡献指南。
如果您发现安全漏洞，请遵循我们的安全政策。
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
Chat with Onyx to get comprehensive answers
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The question to ask Onyx | |
| personaId | No | The ID of the persona to use (default: 15) | |
| chatSessionId | No | Existing chat session ID to continue a conversation (optional) | |
| documentSets | No | List of document set names to search within (empty for all) | |
| enableAutoDetectFilters | No | Whether to enable auto-detection of filters (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'comprehensive answers' but fails to describe key traits such as whether this is a read-only operation, if it requires authentication, rate limits, or how chat sessions are managed. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, clearly stating the tool's core function without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a chat tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It does not explain return values, error handling, or how the tool integrates with the sibling 'search_onyx', leaving the agent with insufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema fully documents all 5 parameters. The description adds no additional meaning beyond what the schema provides, such as explaining how parameters interact or their practical use. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose as 'Chat with Onyx to get comprehensive answers', which identifies the action (chat) and resource (Onyx) but is vague about what distinguishes it from the sibling tool 'search_onyx'. It lacks specificity on how chatting differs from searching, leaving the purpose unclear in context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling 'search_onyx'. The description does not mention alternatives, exclusions, or contextual usage, leaving the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Onyx backend for relevant documents
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The topic to search for | |
| chunksAbove | No | Number of chunks to include above the matching chunk (default: 1) | |
| chunksBelow | No | Number of chunks to include below the matching chunk (default: 1) | |
| retrieveFullDocuments | No | Whether to retrieve full documents instead of just matching chunks (default: false) | |
| documentSets | No | List of document set names to search within (empty for all) | |
| maxResults | No | Maximum number of results to return (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions searching for 'relevant documents' but doesn't describe what constitutes relevance, how results are ranked, whether there are rate limits, authentication requirements, or what the output format looks like. For a search tool with 6 parameters and no annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a tool with a clear primary function and is front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no annotations, no output schema), the description is inadequate. It doesn't explain what 'relevant' means, how results are returned, or provide any behavioral context. For a search tool that likely returns structured data, more completeness is needed to help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, meaning all parameters are documented in the schema itself. The description adds no additional parameter semantics beyond what's already in the schema (e.g., it doesn't explain how 'chunksAbove' and 'chunksBelow' work together or what 'documentSets' represent). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and target ('the Onyx backend for relevant documents'), providing a specific verb+resource combination. However, it doesn't differentiate from its sibling tool 'chat_with_onyx', which appears to be a related but distinct functionality, so it doesn't fully distinguish from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the sibling 'chat_with_onyx' or any other alternatives. It lacks context about appropriate use cases, exclusions, or prerequisites, offering only a basic functional statement without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
chat_with_onyxsearch_onyxScored across 2 tools
The two tools have distinct purposes: one is for interactive chat to get answers, and the other is for searching documents. While both involve querying the Onyx backend, the descriptions clarify that 'chat_with_onyx' provides comprehensive answers through conversation, whereas 'search_onyx' focuses on retrieving relevant documents, reducing ambiguity. However, an agent might still confuse them if the distinction between 'answers' and 'documents' is not clear in practice.
Both tool names follow a consistent verb_noun pattern with 'chat_with_onyx' and 'search_onyx', using snake_case throughout. The naming is predictable and readable, with no deviations or mixed conventions, making it easy for agents to understand the action and target.
With only 2 tools, the server feels thin for a general-purpose 'onyx-mcp-server', as it likely covers a limited scope of interaction with the Onyx backend. This minimal set may not support complex workflows or comprehensive operations, suggesting an under-scoped tool surface that could hinder agent capabilities.
Inferring the domain as interacting with the Onyx backend, the tool set has significant gaps. It lacks CRUD operations (e.g., create, update, delete documents), management functions, or advanced querying beyond basic search and chat. This incomplete coverage will likely cause agent failures when tasks require more than simple retrieval or conversation.
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Let AI agents query data and act across all your business apps via MCP.
