How do I install Onyx MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Onyx MCP need an API key?

The publisher lists these environment variables: ONYX_API_URL, ONYX_API_TOKEN, ONYX_DEFAULT_PERSONA_ID, ONYX_MCP_ENABLE_WEB_FETCH, ONYX_MCP_WEB_FETCH_ALLOWLIST.

What transport does Onyx MCP use?

Onyx MCP runs locally over stdio.

When was Onyx MCP last checked?

Last checked 2026-11-08. Secure MCP access to Onyx search, chat, projects, and administration.

Onyx MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

ONYX_API_URL — Onyx API base URL, for example https://onyx.example.com/api
ONYX_API_TOKEN — Onyx Personal Access Token or API key
ONYX_DEFAULT_PERSONA_ID — Default Onyx agent ID for new chats
ONYX_MCP_ENABLE_WEB_FETCH — Enable web search and allowlisted URL fetching
ONYX_MCP_WEB_FETCH_ALLOWLIST — Comma-separated hostnames permitted for HTTPS URL fetching

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1ONYX_API_URL=<value> ONYX_API_TOKEN=<secret> ONYX_DEFAULT_PERSONA_ID=<value> ONYX_MCP_ENABLE_WEB_FETCH=<value> ONYX_MCP_WEB_FETCH_ALLOWLIST=<value> claude mcp add io.github.bywaleed-onyx-mcp -- npx -y onyx-mcp@0.2.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.bywaleed-onyx-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "ONYX_API_URL": "<value>",11        "ONYX_API_TOKEN": "<secret>",12        "ONYX_DEFAULT_PERSONA_ID": "<value>",13        "ONYX_MCP_ENABLE_WEB_FETCH": "<value>",14        "ONYX_MCP_WEB_FETCH_ALLOWLIST": "<value>"15      }16    }17  }18}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Onyx MCP?

Does Onyx MCP need an API key?

What transport does Onyx MCP use?

When was Onyx MCP last checked?

Documentation

Onyx MCP

Why This Server

Install

Configuration

OpenCode

Claude Desktop

Tool Profiles

Tools

Authentication

Development

Compatibility

Support And Security

License