Onyx MCP Server

Overview

The Onyx MCP Server lets any MCP-compatible LLM client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) access your Onyx knowledge base, web search, and URL fetching capabilities through the Model Context Protocol.

Prerequisites

Before connecting, you’ll need:

A running Onyx instance (either self-hosted or Onyx Cloud)
Authentication — see Personal Access Tokens or API Keys
An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

Self-Hosted MCP Server Configuration

Jump to environment variables, networking, and deployment settings for self-hosted MCP server

Quick Start

Claude Code (CLI)

claude mcp add --transport http onyx https://cloud.onyx.app/mcp \
  --header "Authorization: Bearer YOUR_ONYX_TOKEN_HERE"

Or add it to your project’s .mcp.json:

{
  "mcpServers": {
    "onyx": {
      "type": "http",
      "url": "https://cloud.onyx.app/mcp",
      "headers": {
        "Authorization": "Bearer ${ONYX_TOKEN}"
      }
    }
  }
}

Then set the environment variable before running Claude Code:

export ONYX_TOKEN="your-token-here"
claude

Claude Desktop

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "onyx": {
      "url": "https://cloud.onyx.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ONYX_TOKEN_HERE"
      }
    }
  }
}

Replace https://cloud.onyx.app/mcp with http://YOUR_ONYX_DOMAIN:8090/ if you’re self-hosting.

Cursor / Windsurf / Other MCP Clients

Most MCP clients support HTTP transport with custom headers. The connection details are:

Setting	Value
URL	`https://cloud.onyx.app/mcp` (or `http://YOUR_DOMAIN:8090/`)
Transport	HTTP (Streamable HTTP)
Auth Header	`Authorization: Bearer YOUR_TOKEN`

Refer to your client’s MCP documentation for exact configuration steps.

Available Tools

The MCP server exposes three tools that LLM clients can invoke:

search_indexed_documents

Search your private knowledge base indexed in Onyx. Returns ranked document chunks with content, relevance scores, and metadata.Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Natural language search query
`source_types`	string[]	No	All sources	Filter by connector type (e.g. `["confluence", "github", "jira"]`)
`time_cutoff`	string	No	No cutoff	ISO 8601 datetime — only return docs updated after this time
`limit`	integer	No	`10`	Maximum number of results to return

Example call:

{
  "query": "What is the latest status of PROJ-1234?",
  "source_types": ["jira", "google_drive"],
  "time_cutoff": "2025-01-01T00:00:00Z",
  "limit": 5
}

Response fields:

Field	Description
`documents`	Array of result objects
`documents[].semantic_identifier`	Human-readable document name
`documents[].content`	Relevant text snippet
`documents[].source_type`	Connector source (e.g. `"confluence"`)
`documents[].link`	URL to the original document
`documents[].score`	Relevance score
`total_results`	Number of results returned
`query`	The original query
`executed_queries`	List of queries actually executed (may include expansions)

To discover which source types are available, use the indexed_sources resource (see below).

search_web

Search the public internet for general knowledge and current events.Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search query
`limit`	integer	No	`5`	Maximum number of results

Example call:

{
  "query": "React 19 migration guide",
  "limit": 5
}

Response fields:

Field	Description
`results`	Array of web search results
`results[].title`	Page title
`results[].url`	Page URL
`results[].snippet`	Short text excerpt
`query`	The original query

search_web returns snippets, not full page content. Use open_urls to fetch the complete text of any result.

open_urls

Retrieve the complete text content from one or more web URLs.Parameters:

Parameter	Type	Required	Description
`urls`	string[]	Yes	List of URLs to fetch

Example call:

{
  "urls": [
    "https://react.dev/blog/2024/12/05/react-19",
    "https://react.dev/learn/react-compiler"
  ]
}

Response fields:

Field	Description
`results`	Array of fetched pages
`results[].title`	Page title
`results[].url`	The fetched URL
`results[].content`	Full extracted text content

Available Resources

indexed_sources

URI: resource://indexed_sourcesLists all document connector types currently indexed in your Onyx instance (e.g. "confluence", "github", "google_drive", "slack").Use this to discover valid values for the source_types filter in search_indexed_documents.Example response:

{
  "indexed_sources": ["confluence", "github", "google_drive", "jira", "slack"]
}

Self-Hosted Configuration

To self-host the MCP server, you will need to enable the deployment via environment variables. Docker:

.env

MCP_SERVER_ENABLED=true

Kubernetes:

values.yaml

configMap:
  MCP_SERVER_ENABLED: "true"

Health Check

Verify the MCP server is running:

curl http://localhost:8090/health # or http://YOUR_DOMAIN:8090/health

Expected response:

{
  "status": "healthy",
  "service": "mcp_server"
}

Environment Variables

Most users should not need to configure these environment variables.

Variable	Default	Description
`MCP_SERVER_ENABLED`	`false`	Set to `"true"` to enable the MCP server
`MCP_SERVER_HOST`	`0.0.0.0`	Host to bind the MCP server
`MCP_SERVER_PORT`	`8090`	Port for the MCP server
`MCP_SERVER_CORS_ORIGINS`	(empty)	Comma-separated list of allowed CORS origins
`API_SERVER_PROTOCOL`	`http`	Protocol for internal API server connection
`API_SERVER_HOST`	`127.0.0.1`	Hostname for internal API server connection
`API_SERVER_URL_OVERRIDE_FOR_HTTP_REQUESTS`	(unset)	Full URL override for API server. Use this when self-hosting the MCP server against Onyx Cloud

Debugging & Testing

MCP Inspector

The MCP Inspector is an interactive debugging tool for MCP servers:

npx @modelcontextprotocol/inspector

Setup in Inspector:

Ignore the OAuth configuration menus
Open the Authentication tab
Select Bearer Token authentication
Paste your Onyx PAT or API key
Click Connect

Once connected, you can browse tools, test calls with different parameters, and inspect request/response payloads.

Next Steps

Personal Access Tokens

Create a token to authenticate with the MCP server

API Keys

Create shared API keys for team-wide MCP access

Connectors

Add data sources to make your knowledge searchable via MCP

MCP Actions

Connect Onyx to external MCP servers as a client

Getting Started

Local

Cloud

Authentication

Configuration

Miscellaneous

Overview

Prerequisites

Self-Hosted MCP Server Configuration

Quick Start

Claude Code (CLI)

Claude Desktop

Cursor / Windsurf / Other MCP Clients

Available Tools

Available Resources

Self-Hosted Configuration

Health Check

Environment Variables

Debugging & Testing

MCP Inspector

Next Steps

Personal Access Tokens

API Keys

Connectors

MCP Actions

Getting Started

Local

Cloud

Authentication

Configuration

Miscellaneous

​Overview

​Prerequisites

Self-Hosted MCP Server Configuration

​Quick Start

​Claude Code (CLI)

​Claude Desktop

​Cursor / Windsurf / Other MCP Clients

​Available Tools

​Available Resources

​Self-Hosted Configuration

​Health Check

​Environment Variables

​Debugging & Testing

​MCP Inspector

​Next Steps

Personal Access Tokens

API Keys

Connectors

MCP Actions

Overview

Prerequisites

Quick Start

Claude Code (CLI)

Claude Desktop

Cursor / Windsurf / Other MCP Clients

Available Tools

Available Resources

Self-Hosted Configuration

Health Check

Environment Variables

Debugging & Testing

MCP Inspector

Next Steps