This is the server that lets other apps search Onyx. To let Onyx call tools on an external MCP server,
see MCP plugins.
Deployment requirements
Use a running Onyx deployment with indexed documents and user access configured. The MCP service must be able to reach the Onyx API and the deployment’s backing services. SetWEB_DOMAIN to the public HTTPS address users visit, for example https://onyx.example.com.
Onyx derives both its OAuth issuer and MCP resource URL from this value:
OAuth is available automatically when
WEB_DOMAIN is a valid HTTPS URL.
HTTP is accepted only for loopback development addresses such as http://localhost:3000.
A non-loopback HTTP address does not enable the OAuth provider. There is no separate OAuth enablement flag.
The MCP endpoint, OAuth endpoints, discovery metadata,
and browser authorization pages must be reachable at the public address in WEB_DOMAIN.
An API reachable only on another hostname is insufficient:
the OAuth API routes must also be served on the WEB_DOMAIN host.
Enable the service
Docker Compose
The bundled Compose files (docker-compose.yml and docker-compose.prod.yml) include the mcp_server service.
It starts by default. In the deployment’s .env, set your public address and keep the service enabled:
MCP_SERVER_ENABLED=false to turn the service off. The container then idles and nginx does not load the MCP routes.
After you change these values, recreate the MCP service and nginx from the Docker Compose deployment directory:
WEB_DOMAIN, recreate the affected API, web,
and MCP services as part of your deployment update so they use the new value.
The included nginx startup configuration loads the MCP routing rules when MCP_SERVER_ENABLED=true.
Kubernetes with Helm
The chart enables the MCP service by default (mcpServer.enabled: true).
Set it to false to remove the deployment and its routes. To set it explicitly, add the following to your Helm values:
MCP_SERVER_ENABLED=true in the MCP container.
Setting a ConfigMap flag without mcpServer.enabled=true does not create the service.
When using the chart’s ingress, configure the web hostname and TLS to match WEB_DOMAIN.
The chart includes MCP discovery routes, authorization metadata routes, and the browser callback route.
It also serves the OAuth API routes on the web hostname when the API and web ingress hostnames differ.
If you use a custom ingress or proxy, provide equivalent routing as described below.
Upgrade an existing installation
Deploy matching Onyx versions for the API, web, MCP, and background services. Apply the normal database migrations for the release and restart the affected services. OAuth grants and tokens use database records introduced by the feature; updating only the MCP container is insufficient. Self-hosted installations with a customPOSTGRES_DEFAULT_SCHEMA store OAuth client registrations in that schema.
The release migration moves earlier registrations out of public and keeps their client IDs.
Keep the background workers and scheduled tasks running for expired-grant cleanup.
Expired credentials stop working at their expiration time even if cleanup has not yet removed their database records.
Configure public routing
The bundled nginx configuration and Helm templates provide these routes. Use this table when checking a custom reverse proxy:
Preserve authorization headers,
WWW-Authenticate response headers, and the forwarded host and protocol.
Support HTTP streaming and sufficiently long request timeouts for MCP requests.
Serve discovery metadata publicly without a login redirect or an authentication gateway challenge;
clients need it before they can sign in.
The /mcp/oauth/callback page belongs to the web application and must take precedence over the general MCP proxy route.
It supports Onyx’s browser OAuth callback flow; it is separate from an external client’s own registered redirect URI.
Verify the deployment
Run these checks from a machine with access to the public deployment. They do not require a token.Protected resource metadata
resource,
lists https://onyx.example.com/api/oauth-provider under authorization_servers,
and advertises read:search under scopes_supported.
Onyx accepts the MCP resource with or without its trailing slash.
Use the advertised resource value when building a custom client.
Authorization server metadata
issuer is https://onyx.example.com/api/oauth-provider. The response includes authorization, token,
registration, and revocation endpoints under that issuer. It advertises the authorization code and refresh token grants,
the read:search scope, PKCE S256, and public client authentication (none).
A login page, HTML response,
or unexpected redirect at either discovery URL usually indicates a routing or authentication gateway problem.
Authentication challenge
401 Unauthorized and a WWW-Authenticate challenge pointing to the protected resource metadata.
Complete an authenticated connection using the client setup
guide
to verify that a user can search their indexed documents.
Authentication and access
OAuth lets a user sign in to Onyx in their browser and approve an app’s access without copying a token into that app. The supported scope,read:search, gives the client search access associated with the signed-in user.
OAuth does not grant administrator access or bypass document permissions. To authorize an OAuth connection,
the user must have an active standard account with Search and Create User Access Token permissions.
Check these permissions if a user cannot approve a connection.
For clients that accept bearer tokens instead of OAuth,
use a personal access token
or an API key.
A personal token is appropriate when access should follow an individual user.
OAuth client requirements
Most users should let their MCP client handle discovery and registration. For a custom client integration, Onyx supports:- Public clients: use
token_endpoint_auth_method=none. A client secret is not required. - Dynamic client registration: register client metadata at the advertised registration endpoint. Onyx removes registrations that have been idle for 90 days.
- Client ID Metadata Documents (CIMD): a client can use the HTTPS URL of its metadata document as its
client_id. Onyx fetches the document during authorization. The document’sclient_idmust equal that URL, and the URL must be publicly reachable: private or blocked destinations are rejected as an invalid client. A fetch failure returns503; an invalid document returns an invalid-client error. A document can declare another token authentication method, such asprivate_key_jwt. Onyx then serves the client as a public client and ignores any client assertion. Onyx rejects such a document as an invalid client if any of its redirect URIs is a loopback address. - Public client metadata: one to ten redirect URIs,
authorization_codegrant, andcoderesponse type, for both registration methods. - Authorization code flow with PKCE: use
code_challenge_method=S256and supply the matching verifier when exchanging the code. - Resource binding: use the canonical MCP resource,
https://onyx.example.com/mcp/, in authorization and token requests. - Registered redirect URIs: the callback must match the client’s registration. Wildcards are unsupported. Loopback callbacks support a variable port for desktop clients, while preserving the registered scheme, hostname, path, and query.
Token lifetime and revocation
Access tokens last up to 15 minutes. When a refresh token is issued, its grant lasts 30 days from the original authorization; refreshing does not extend that deadline. Without a refresh token, the grant has the access-token lifetime. Refresh tokens rotate: save each newly returned refresh token and discard the previous one. Reusing a consumed refresh token revokes the grant, so concurrent refresh attempts can require the user to reconnect. Serialize refresh operations for a connection. Onyx deletes expired grants and their tokens daily. Clients can revoke tokens through the advertised revocation endpoint. Users can review and revoke OAuth connections in Onyx. A revoked grant stops authorizing requests; the client must obtain a new user authorization to reconnect.Service settings
The Helm chart supplies the MCP service’s API URL. Configure an override only when your deployment topology requires it;
it does not change the public OAuth issuer or MCP resource.
Troubleshooting
Preserve the actual error status in your proxy. A permission, billing,
or upstream availability problem should not be rewritten into a generic sign-in failure.