Skip to content
MCP server

Onyx MCP

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

Runs locallyStatus and history
Install
Pricing
Open source
Runs
Locally
Version
0.2.1
Listing updated
6 days ago

About Onyx MCP

Onyx MCP is an open-source MCP server. It runs locally on your machine and is started by your AI client.

Install

Run in a terminal

claude mcp add onyx-mcp --env ONYX_API_URL='<ONYX_API_URL>' --env ONYX_API_TOKEN='<ONYX_API_TOKEN>' -- npx -y onyx-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "onyx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "onyx-mcp"
      ],
      "env": {
        "ONYX_API_URL": "<ONYX_API_URL>",
        "ONYX_API_TOKEN": "<ONYX_API_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "onyx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "onyx-mcp"
      ],
      "env": {
        "ONYX_API_URL": "<ONYX_API_URL>",
        "ONYX_API_TOKEN": "<ONYX_API_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "onyx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "onyx-mcp"
      ],
      "env": {
        "ONYX_API_URL": "<ONYX_API_URL>",
        "ONYX_API_TOKEN": "<ONYX_API_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "onyx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "onyx-mcp"
      ],
      "env": {
        "ONYX_API_URL": "<ONYX_API_URL>",
        "ONYX_API_TOKEN": "<ONYX_API_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "onyx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "onyx-mcp"
      ],
      "env": {
        "ONYX_API_URL": "<ONYX_API_URL>",
        "ONYX_API_TOKEN": "<ONYX_API_TOKEN>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • ONYX_API_URLOnyx API base URL, for example https://onyx.example.com/apiRequired
  • ONYX_API_TOKENOnyx Personal Access Token or API keyRequired
  • ONYX_DEFAULT_PERSONA_IDDefault Onyx agent ID for new chats
  • ONYX_MCP_ENABLE_WEB_FETCHEnable web search and allowlisted URL fetching
  • ONYX_MCP_WEB_FETCH_ALLOWLISTComma-separated hostnames permitted for HTTPS URL fetching

Pricing

Open source

Onyx MCP FAQ

Is Onyx MCP free?

Yes. Onyx MCP is open source, so you can use and self-host it for free.

How do I add Onyx MCP to Claude Code?

Run this command in your terminal: claude mcp add onyx-mcp --env ONYX_API_URL='<ONYX_API_URL>' --env ONYX_API_TOKEN='<ONYX_API_TOKEN>' -- npx -y onyx-mcp

Where this comes from

  • Description: from the official MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers