Onyx MCP

io.github.ByWaleedPublished by GitHub account ByWaleedv0.2.1Updated Oct 24, 2026

Secure MCP access to Onyx search, chat, projects, and administration.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

Gives an assistant read-only access to an Onyx (formerly Danswer) instance for search, chat history, agents, projects, and connector status.

What you can do
A local stdio MCP server that connects to an Onyx deployment and exposes its search, chat, agent, project, file, document-set, tool, source, and connector-status APIs. It starts in a read-only profile; write, admin, destructive, raw-API, and web-fetch capabilities are separate opt-in profiles. A capabilities tool reports the active profile, and an advanced raw API tool covers deployment-specific endpoints.
When to use it
Use it when an assistant should search and read an existing Onyx knowledge base, review chat history, or inspect agents, projects, and connector status. It is also useful when you want to grant write or administrative actions later without changing servers, since each capability is gated by its own setting.
Requirements
Node.js 20 or 22 and npx to run the onyx-mcp package locally. Requires ONYX_API_URL (the Onyx API base URL) and ONYX_API_TOKEN (an Onyx personal access token or API key). Optional settings include ONYX_DEFAULT_PERSONA_ID and the enable flags for write, admin, destructive, raw API, and web fetch, plus ONYX_MCP_WEB_FETCH_ALLOWLIST. Network access to the Onyx instance is needed.
Before you install
ONYX_API_TOKEN is a secret and client configuration files containing it should be treated as sensitive and permission-restricted. Write, admin, destructive, and raw API profiles are off by default but can create, modify, or delete data once enabled; destructive tools require confirmation and bulk deletion is not exposed. The raw API tool requires admin and, for non-GET requests, write and destructive access. Web fetch is off by default and only allows HTTPS hosts on the allowlist. Onyx still…

Installation

In SourceWeft

  1. Open Onyx MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
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:

VariableDescription
ONYX_API_URLOnyx API base URL, for example https://onyx.example.com/api
ONYX_API_TOKENOnyx PAT or API key

Optional:

VariableDefaultDescription
ONYX_DEFAULT_PERSONA_ID0Default agent used for new chats
ONYX_MCP_ENABLE_WRITEfalseRegisters tools that create or modify data
ONYX_MCP_ENABLE_ADMINfalseRegisters administrative tools
ONYX_MCP_ENABLE_DESTRUCTIVEfalseRegisters destructive tools; write must also be enabled
ONYX_MCP_ENABLE_RAW_APIfalseRegisters the advanced raw API tool; admin access is also required
ONYX_MCP_ENABLE_WEB_FETCHfalseRegisters web search and URL-fetching tools
ONYX_MCP_WEB_FETCH_ALLOWLISTemptyComma-separated hostnames allowed for HTTPS URL fetching
ONYX_MCP_TIMEOUT_MS30000Request timeout
ONYX_MCP_MAX_RESPONSE_BYTES1000000Maximum accepted response body
ONYX_MCP_MAX_CONCURRENCY8Maximum concurrent requests to Onyx
ONYX_MCP_MAX_QUEUE100Maximum requests waiting for a concurrency slot

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

OpenCode

json
{  "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

json
{  "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

bash
npm cinpm run verify

Compatibility

ComponentSupported
Node.js20 and 22
MCP SDK/protocolTypeScript SDK 1.x, MCP through 2025-11-25
OnyxCurrent community and enterprise APIs; tested against the repository version documented in releases
TransportLocal stdio

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

License

MIT

Source: README.md at commit 36216d8

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts