Onyx MCP

Onyx MCP

[CI] [License: MIT]

MCP Registry name: io.github.ByWaleed/onyx-mcp

A comprehensive, secure Model Context Protocol server for Onyx, formerly Danswer.

This project exposes Onyx search, chat, agents, projects, documents, connectors, ingestion, and deployment-specific APIs to MCP clients. It is an independent community project and is not an official Onyx package.

Why This Server

• Uses the current /chat/send-chat-message contract.
• Defaults to Onyx's built-in assistant, persona 0.
• Supports scoped Personal Access Tokens and legacy API keys.
• Starts read-only.
• Separately gates writes, administration, destructive actions, and raw API access.
• Applies request timeouts and response-size limits.
• Never logs authorization headers or tokens.
• Includes an advanced raw API tool for deployment-specific endpoints.

Install

npx -y [email protected]

The pinned command is recommended for reproducible execution. Use npx -y onyx-mcp@latest only if you intentionally want automatic upgrades.

Versioned tarballs are attached to GitHub Releases. The previous scoped package, @bywaleed/onyx-mcp, is deprecated in favor of onyx-mcp.

Configuration

Required:

Optional:

Onyx still enforces the permissions attached to the supplied token. Enabling a profile cannot grant additional Onyx privileges.

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"      }    }  }}

Tool Profiles

The read-only profile includes health, identity, permissions, search, chat history, agents, projects, files, tools, document sets, and connector status.

The write profile adds chat creation, chat messages, feedback, and project updates.

The admin profile adds connector, credential, user, agent, and direct-ingestion administration.

The destructive profile adds individually confirmed deletion tools. Bulk deletion is intentionally not exposed as a first-class tool.

The raw API profile adds onyx_api_request. It covers APIs specific to an Onyx edition or version. Every raw request requires the admin profile. Every non-GET request also requires write and destructive access plus confirmation because arbitrary endpoint semantics cannot be inferred safely.

Tools

The default profile provides health, version, identity, permission, indexed search, agent, chat-history, project, file, document-set, tool, source, and connector-status tools. Write mode adds chat, feedback, and project mutations. Admin mode adds connector, credential, user, agent, and ingestion tools. Web search and URL fetching require a separate web-fetch opt-in. URL fetching accepts only HTTPS destinations matching the configured hostname allowlist; Onyx must also validate redirects and resolved addresses to prevent DNS rebinding.

Run onyx_capabilities to inspect the active profile. MCP clients can also call tools/list for complete machine-readable schemas and safety annotations.

Authentication

Prefer an Onyx PAT with the smallest required scope:

• read:search for search.
• read:chat for chat history.
• write:chat for chat creation and messages.

Some Onyx endpoints still use legacy role checks and need an unrestricted PAT or API key. Use a separate administrative server configuration for those operations.

Treat client configuration files as sensitive when they contain a token. Use a dedicated least-privilege token and restrict file permissions to your user account.

Development

npm cinpm run verify

Compatibility

The server uses non-streaming Onyx chat responses for a stable MCP result. Onyx editions and releases expose different administrative routes. The raw API tool provides an escape hatch while first-class tools remain curated and safe. MCP SDK 2.x migration is planned as a separate breaking compatibility release.

Support And Security

• Usage questions: GitHub Discussions
• Bugs and feature requests: GitHub Issues
• Vulnerabilities: private security advisory
• Release history: CHANGELOG.md
• Maintainer release process: RELEASING.md
• MCP Registry metadata: server.json

License

MIT