Onyx MCP

Onyx MCP

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

适用于 Onyx（前身为 Danswer）的全面、安全的 Model Context Protocol 服务。

本项目向 MCP 客户端提供 Onyx 搜索、聊天、Agent、项目、文档、连接器、数据摄取和特定部署的 API。这是一个独立的社区项目，并非官方 Onyx 软件包。

为什么选择此服务

• 使用当前的 /chat/send-chat-message 接口约定。
• 默认使用 Onyx 内置助手，persona 为 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	新建聊天时使用的默认 Agent
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"
      }
    }
  }
}

工具配置文件

只读配置文件包含健康状态、身份、权限、搜索、聊天历史记录、Agent、项目、文件、工具、文档集和连接器状态。

写入配置文件在此基础上增加聊天创建、聊天消息、反馈和项目更新。

管理员配置文件在此基础上增加连接器、凭据、用户、Agent 和直接导入管理功能。

破坏性操作配置文件在此基础上增加需要逐项确认的删除工具。我们有意不将批量删除作为一等工具提供。

原始 API 配置文件在此基础上增加 onyx_api_request。它涵盖特定于 Onyx 版本或发行版的 API。每个原始请求都需要管理员配置文件。由于无法安全推断任意端点的语义，每个非 GET 请求还需要写入和破坏性操作权限及确认。

工具

默认配置文件提供健康状态、版本、身份、权限、索引搜索、Agent、聊天历史记录、项目、文件、文档集、工具、来源和连接器状态工具。写入模式会增加聊天、反馈和项目变更功能。管理员模式会增加连接器、凭据、用户、Agent 和数据导入工具。网络搜索和 URL 获取需要单独启用网络获取功能。URL 获取仅接受与配置的主机名允许列表匹配的 HTTPS 目标；Onyx 还必须验证重定向和解析出的地址，以防止 DNS 重绑定。

运行 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，MCP 至 2025-11-25
Onyx	当前社区版和企业版 API；已针对发行说明中记录的仓库版本进行测试
传输方式	本地 stdio

服务器使用非流式 Onyx 聊天响应，以获得稳定的 MCP 结果。不同 Onyx 版本和发行版提供的管理路由各不相同。原始 API 工具提供了变通方案，同时一等工具仍经过筛选且安全。MCP SDK 2.x 迁移计划作为单独的破坏性兼容版本发布。

支持与安全

• 使用问题：GitHub 讨论区
• 错误和功能请求：GitHub Issues
• 漏洞：私密安全公告
• 发行历史：CHANGELOG.md
• 维护者发布流程：RELEASING.md
• MCP Registry 元数据：server.json

许可证

MIT