Onyx AI ナレッジ ベースとシームレスに統合するモデル コンテキスト プロトコル (MCP) サーバー。
このMCPサーバーは、MCP対応クライアントをOnyxナレッジベースに接続し、ドキュメントから関連するコンテキストを検索・取得できるようにします。MCPクライアントとOnyx API間の橋渡しとなり、強力なセマンティック検索とチャット機能を実現します。
強化された検索: LLM 関連性フィルタリングを使用した Onyx ドキュメント セット全体のセマンティック検索
コンテキストウィンドウの取得: 一致するチャンクの上下のチャンクを取得して、コンテキストをより良く把握します。
完全な文書の取得: チャンクではなく文書全体を取得するオプション
チャット統合: LLM + RAGとOnyxの強力なチャットAPIを使用して包括的な回答を得る
設定可能なドキュメント セット フィルタリング: 特定のドキュメント セットをターゲットにして、より関連性の高い結果を得ることができます。
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 buildOnyx 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 クライアントは次の 2 つの強力なツールにアクセスできるようになります。
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ツールは、LLM + RAG を備えた Onyx の強力なチャット API を活用して包括的な回答を提供します。
<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このプロジェクトでは、すべてのコミットメッセージにConventional Commits仕様を適用します。これを容易にするために、対話型のコミットツールを提供しています。
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リンティングの問題を修正:
npm run lint:fixこのプロジェクトでは、継続的インテグレーションとデプロイメントにGitHub Actionsを使用しています。CIパイプラインは、メインブランチへのプッシュとプルリクエストごとに実行され、以下のチェックを実行します。
リンティング
建物
テスト
コードカバレッジレポート
PRがメインブランチにマージされると、プロジェクトは適切なバージョンアップの種類を自動的に決定し、npmに公開します。システムはPRのタイトルとコミットメッセージの両方を分析して、バージョンアップの種類を決定します。
PR タイトルの検証: すべての PR タイトルはConventional Commits仕様に基づいて検証されます。
PR のタイトルはタイプで始まる必要があります (例: feat: 、 fix: 、 docs: )
この検証はPRが作成または更新されたときに自動的に行われます
無効なタイトルのPRは検証チェックに失敗します
コミット メッセージの検証: すべてのコミット メッセージは、従来のコミット形式に対しても検証されます。
コミットメッセージはタイプで始まる必要があります（例： feat: 、 fix: 、 docs: ）
これはコミット時に実行されるgitフックによって強制されます
無効なメッセージを含むコミットは拒否されます
対話型のコミットメッセージ作成ツールとしてnpm run commit使用する
バージョン バンプの決定: システムは PR タイトルとコミット メッセージの両方を分析して、適切なバージョン バンプを決定します。
PRタイトルがfeatで始まるか、新機能を含む場合 → マイナーバージョンアップ
fixで始まるかバグ修正を含むPRタイトル → パッチバージョンのアップ
PRタイトルにBREAKING CHANGEまたは感嘆符が含まれる → メジャーバージョンアップ
PRタイトルが特定のバンプタイプを示していない場合、システムはコミットメッセージを分析します。
コミットメッセージで見つかった最も優先度の高いバンプタイプが使用されます（メジャー > マイナー > パッチ）
従来のコミットプレフィックスが見つからない場合、システムは自動的にパッチバージョンのバンプをデフォルトに設定し、失敗することはありません。
バージョンの更新と公開:
セマンティックバージョニングに従って、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.
