Onyx MCP

Onyx MCP

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:

Variable	Description
ONYX_API_URL	Onyx API base URL, for example https://onyx.example.com/api
ONYX_API_TOKEN	Onyx PAT or API key

Optional:

Variable	Default	Description
ONYX_DEFAULT_PERSONA_ID	0	Default agent used for new chats
ONYX_MCP_ENABLE_WRITE	false	Registers tools that create or modify data
ONYX_MCP_ENABLE_ADMIN	false	Registers administrative tools
ONYX_MCP_ENABLE_DESTRUCTIVE	false	Registers destructive tools; write must also be enabled
ONYX_MCP_ENABLE_RAW_API	false	Registers the advanced raw API tool; admin access is also required
ONYX_MCP_ENABLE_WEB_FETCH	false	Registers web search and URL-fetching tools
ONYX_MCP_WEB_FETCH_ALLOWLIST	empty	Comma-separated hostnames allowed for HTTPS URL fetching
ONYX_MCP_TIMEOUT_MS	30000	Request timeout
ONYX_MCP_MAX_RESPONSE_BYTES	1000000	Maximum accepted response body
ONYX_MCP_MAX_CONCURRENCY	8	Maximum concurrent requests to Onyx
ONYX_MCP_MAX_QUEUE	100	Maximum 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

{
  "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 ci
npm run verify

Compatibility

Component	Supported
Node.js	20 and 22
MCP SDK/protocol	TypeScript SDK 1.x, MCP through 2025-11-25
Onyx	Current community and enterprise APIs; tested against the repository version documented in releases
Transport	Local 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

• 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