Onyx MCP

Onyx MCP

MCP Registry 名：io.github.ByWaleed/onyx-mcp

Onyx（旧称 Danswer）向けの、包括的で安全な Model Context Protocol サーバーです。

このプロジェクトは、Onyx の検索、チャット、エージェント、プロジェクト、ドキュメント、コネクター、取り込み、デプロイ環境固有の API を MCP クライアントに公開します。これは独立したコミュニティプロジェクトであり、Onyx の公式パッケージではありません。

このサーバーを選ぶ理由

• 現行の /chat/send-chat-message コントラクトを使用します。
• Onyx 組み込みのアシスタント（ペルソナ 0）をデフォルトで使用します。
• スコープ付き Personal Access Token と従来の API キーに対応しています。
• 読み取り専用で起動します。
• 書き込み、管理、破壊的操作、未加工 API アクセスを個別に制御します。
• リクエストのタイムアウトとレスポンスサイズの上限を適用します。
• 認証ヘッダーやトークンをログに記録することはありません。
• デプロイ環境固有のエンドポイント向けに、高度な未加工 API ツールを含みます。

インストール

npx -y [email protected]

再現可能な実行には、バージョンを固定したコマンドを推奨します。自動アップグレードを意図的に行う場合に限り、npx -y onyx-mcp@latest を使用してください。

バージョン付き tarball は GitHub Releases に添付されています。以前のスコープ付きパッケージ @bywaleed/onyx-mcp は非推奨となり、onyx-mcp に置き換えられました。

設定

必須：

変数	説明
ONYX_API_URL	Onyx API のベース URL（例：https://onyx.example.com/api）
ONYX_API_TOKEN	Onyx PAT または API キー

任意：

変数	デフォルト	説明
ONYX_DEFAULT_PERSONA_ID	0	新しいチャットで使用するデフォルトのエージェント
ONYX_MCP_ENABLE_WRITE	false	データを作成または変更するツールを登録します
ONYX_MCP_ENABLE_ADMIN	false	管理ツールを登録します
ONYX_MCP_ENABLE_DESTRUCTIVE	false	破壊的操作を行うツールを登録します。書き込みも有効にする必要があります
ONYX_MCP_ENABLE_RAW_API	false	高度な未加工 API ツールを登録します。管理者アクセスも必要です
ONYX_MCP_ENABLE_WEB_FETCH	false	ウェブ検索と URL 取得のツールを登録します
ONYX_MCP_WEB_FETCH_ALLOWLIST	空	HTTPS URL の取得を許可するホスト名をカンマ区切りで指定します
ONYX_MCP_TIMEOUT_MS	30000	リクエストのタイムアウト
ONYX_MCP_MAX_RESPONSE_BYTES	1000000	受け入れるレスポンス本文の最大サイズ
ONYX_MCP_MAX_CONCURRENCY	8	Onyx への同時リクエストの最大数
ONYX_MCP_MAX_QUEUE	100	同時実行枠を待機できるリクエストの最大数

Onyx は引き続き、指定されたトークンに付与された権限を適用します。プロファイルを有効にしても、Onyx の権限が追加で付与されることはありません。

OpenCode

{
  "mcp": {
    "onyx": {
      "type": "local",
      "command": ["npx", "-y", "[email protected]"],
      "environment": {
        "ONYX_API_URL": "https://onyx.example.com/api",
        "ONYX_API_TOKEN": "{env:ONYX_API_TOKEN}"
      },
      "enabled": true
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "onyx": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "ONYX_API_URL": "https://onyx.example.com/api",
        "ONYX_API_TOKEN": "your-token"
      }
    }
  }
}

ツールプロファイル

読み取り専用プロファイルには、ヘルスチェック、ID、権限、検索、チャット履歴、エージェント、プロジェクト、ファイル、ツール、ドキュメントセット、コネクターのステータスが含まれます。

書き込みプロファイルでは、チャットの作成、チャットメッセージ、フィードバック、プロジェクトの更新が追加されます。

管理者プロファイルでは、コネクター、認証情報、ユーザー、エージェント、直接取り込みの管理機能が追加されます。

破壊的操作プロファイルでは、個別に確認する削除ツールが追加されます。一括削除は、意図的に第一級のツールとして公開していません。

raw API プロファイルでは、onyx_api_request が追加されます。Onyx のエディションやバージョンに固有の API に対応します。すべての raw リクエストには管理者プロファイルが必要です。また、任意のエンドポイントの動作を安全に推測できないため、GET 以外のすべてのリクエストには、書き込みおよび破壊的操作へのアクセスと確認が必要です。

ツール

デフォルトのプロファイルでは、ヘルスチェック、バージョン、ID、権限、インデックス検索、エージェント、チャット履歴、プロジェクト、ファイル、ドキュメントセット、ツール、ソース、コネクターのステータスに関するツールが提供されます。書き込みモードでは、チャット、フィードバック、プロジェクトの変更が追加されます。管理者モードでは、コネクター、認証情報、ユーザー、エージェント、取り込みに関するツールが追加されます。ウェブ検索と URL の取得には、別途ウェブ取得のオプトインが必要です。URL の取得では、設定されたホスト名許可リストに一致する HTTPS の接続先のみが受け付けられます。また、DNS リバインディングを防ぐため、Onyx はリダイレクト先と解決済みアドレスも検証する必要があります。

onyx_capabilities を実行すると、アクティブなプロファイルを確認できます。MCP クライアントは tools/list を呼び出して、機械可読な完全なスキーマと安全性に関する注釈を取得することもできます。

認証

必要最小限のスコープを持つ Onyx PAT を使用してください。

• 検索には read:search。
• チャット履歴には read:chat。
• チャットの作成とメッセージには write:chat。

一部の Onyx エンドポイントでは、従来のロールチェックが引き続き使われており、制限のない PAT または API キーが必要です。それらの操作には、別個の管理用サーバー設定を使用してください。

トークンを含むクライアント設定ファイルは、機密情報として扱ってください。専用の最小権限トークンを使用し、ファイルのアクセス権を自身のユーザーアカウントに制限してください。

開発

npm ci
npm run verify

互換性

コンポーネント	サポート対象
Node.js	20 および 22
MCP SDK／プロトコル	TypeScript SDK 1.x、2025-11-25 までの MCP
Onyx	現行のコミュニティ版およびエンタープライズ版の API。リリースに記載されたリポジトリのバージョンでテスト済み
トランスポート	ローカル stdio

このサーバーでは、安定した MCP の結果を得るために、Onyx の非ストリーミングチャット応答を使用します。Onyx のエディションやリリースによって、公開される管理用ルートは異なります。第一級のツールを厳選された安全な状態に保ちながら、raw API ツールで代替手段を提供します。MCP SDK 2.x への移行は、別途、互換性を破るリリースとして予定されています。

サポートとセキュリティ

• 使用方法に関する質問：GitHub Discussions
• バグ報告と機能リクエスト：GitHub Issues
• 脆弱性：非公開のセキュリティアドバイザリー
• リリース履歴：CHANGELOG.md
• メンテナーのリリース手順：RELEASING.md
• MCP Registry のメタデータ：server.json

ライセンス

MIT