MCP

In Onyx 5.0, MCP servers moved from their own admin page to Admin Panel → Plugins. See Where things moved.

An MCP plugin connects Onyx to a server that uses the Model Context Protocol. Onyx is the MCP client. It discovers the tools on the server, and agents call those tools during a conversation. MCP plugins work in default Chat, in custom agents, and in Craft. Use an MCP plugin when a vendor publishes an MCP server, when you run your own server, or when no built-in Craft App exists for the application.

To let other MCP clients use Onyx as a server, see Onyx MCP Server.

Add an MCP server

Open the MCP catalog

Go to Admin Panel → Plugins, click Add, then select MCP.

The MCP catalog with Slack, HubSpot, Asana, Linear, Notion, Sentry, Atlassian, and Add custom MCP server

Select a catalog entry to fill in the server name and URL for that vendor. The catalog contains Slack, HubSpot, Asana, Linear, Notion, Sentry, and Atlassian. Select Add custom MCP server for any other server.

Enter the server details

Enter a Server Name and the MCP Server URL. Onyx checks the server and shows the authentication method and connection transport that it detects.

The Add MCP Server dialog after Onyx detects no authentication and the Streamable HTTP transport

Catalog entries also show a Setup guide link to the vendor’s documentation.

The Add MCP Server dialog for Linear with OAuth detected

The Onyx API server must be able to reach the URL. Onyx blocks private, loopback, and link-local addresses during setup checks.

Set availability

On the same page, set who can use the server and where it is available:

Setting	Effect
Access control	Public lets all users use the server. Select users or groups to limit access.
Enable in default Chat	Makes the tools available in chats without a custom agent.
Enable for Craft	Makes the tools available in Craft sessions and scheduled tasks. This switch shows only when Craft is enabled.

Click Continue.

Configure authentication

Select an Authentication Method. Onyx marks the method it detected as Recommended. See Authentication for each method.

The Authentication Method menu with OAuth, API Key, and No authentication

Connect

Click Connect. Onyx connects to the server, lists its tools, and opens the server’s settings.

Authentication

Method	Who signs in	Use it when
No authentication	Nobody	The server is public, or a network control protects it.
API Key, shared	The admin, once for everyone	All users can share one service account.
API Key, personal	Each user	Each user has a personal token, and the server must apply that user’s permissions.
OAuth	Each user	The server supports OAuth. Each user signs in with their own account.
Pass-through	Each user, with their Onyx sign-in	Onyx sends the user’s Onyx OAuth token to the server. This method shows only when Onyx sign-in uses OAuth, OIDC, or Google OAuth.

With personal API keys and OAuth, each user connects their own account from the Plugins page. The MCP server then returns only data that the user’s account can access.

OAuth

OAuth is the best choice for most hosted vendor servers, such as Linear, Notion, Atlassian, and Sentry.

Option	Effect
Set up automatically	Onyx registers an OAuth client with the server’s published settings. Use this when the server supports dynamic client registration.
Use your own OAuth client	Enter a client ID from your provider. Add a client secret only if the provider requires it.
Use client metadata document	The provider fetches the Onyx client metadata document over the public internet. Turn this off if your Onyx instance is private. Onyx then uses automatic client registration.

If you create your own OAuth client, set its redirect URI to:

https://<your-onyx-domain>/mcp/oauth/callback

Onyx builds OAuth callback URLs from WEB_DOMAIN. Set WEB_DOMAIN to the URL that users open in their browser.

API key

Choose whether each user connects with a personal token or everyone uses a shared token. Enter a key to test the server and load its tools. A test key is saved to your account only.

Advanced settings

Expand Advanced settings to add custom headers or change the transport.

Custom Headers are sent with every request. Use {api_key} for each user’s API key and {user_email} for the user’s email address. Any other {placeholder} asks each user for a value when they connect.
Connection transport is Streamable HTTP by default. Select SSE only if the server requires legacy SSE. Onyx does not detect this setting.

Manage tools

Open the server from the Plugins page, then select the Tools tab.

The Tools tab with the list of tools from an MCP server

In Available tools, turn tools on or off for the whole workspace. Use Enable all or Disable all tools for bulk changes.
Click Refresh tools after the server adds, removes, or changes tools.
Click Save Changes to apply your changes.

When Craft is enabled, the Approval settings tab sets the Craft policy for each tool.

Approval settings with Auto-approve, Ask, and Disabled for each tool

Policy	Effect in Craft
Auto-approve	The tool runs without a prompt.
Ask	Craft asks the user to approve each call.
Disabled	Craft never runs the tool.

Use Permissions to set all tools at once. Tool availability and Craft policies are separate. A tool that you turn off in Available tools is not available anywhere.

Approval policies apply only in Craft. In default Chat and custom agents, agents call enabled MCP tools without a prompt.

Configuration tab

Setting	Effect
Server Name and Description	Shown to users on the Plugins page.
Access control	Selects who can use the server.
Enable in default Chat	Adds or removes the server from default Chat for the workspace. Custom agents keep their tools.
Enable for Craft	Adds or removes the server from Craft.
Let users manage approval settings	Lets users change Craft approval policies for tools that you did not disable.

If you change the server URL, Onyx removes the stored connections for that server. Users must connect again.

Use MCP tools in custom agents

Open the agent editor and select the MCP server under Actions. Then select the tools the agent can use. A custom agent keeps its MCP tools when you turn off Enable in default Chat. See Agents.

Getting Started

Language Models

Connectors

Managing Features

Access Control

Advanced Configs

Auditing

Plans & Billing

Miscellaneous

Add an MCP server