Skip to main content
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

1

Open the MCP catalog

Go to Admin Panel → Plugins, click Add, then select MCP.The MCP catalog with Linear, Notion, Sentry, Atlassian, and Add custom MCP serverSelect a catalog entry to fill in the server name and URL for that vendor. Select Add custom MCP server for any other server.
2

Enter the server details

Enter a Server Name and the MCP Server URL. Onyx checks the server and shows the authentication method, connection transport, and client metadata document support that it detects.The Add MCP Server dialog after Onyx detects no authentication and the Streamable HTTP transportThe Onyx API server must be able to reach the URL. Onyx blocks private, loopback, and link-local addresses during setup checks.
3

Set availability

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

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 authenticationClick Connect. Onyx lists the server’s tools and opens its settings.

Authentication

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. OAuth settings with Set up automatically, Use your own OAuth client, and Use client metadata document If you create your own OAuth client, set its redirect URI to:
Onyx builds OAuth callback URLs from WEB_DOMAIN. Set WEB_DOMAIN to the URL that users open in their browser.

API key

API Key settings with a choice of personal or shared token and a test credential field Enter a key to test the server and load its tools. A test key is saved to your account only.

Advanced settings

Advanced settings with Custom Headers and Connection 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. Onyx tries Streamable HTTP first and then SSE during the setup check. Select SSE (legacy) only if the server supports SSE alone.

Manage tools

The Tools tab with the list of tools from an MCP server
  • In Available tools, turn tools on or off for the whole workspace.
  • Click Refresh tools after the server adds, removes, or changes tools. Save or discard pending changes first.
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 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

The Configuration tab for an MCP server If you change the server URL, Onyx removes the stored connections for that server. Users must connect again. To delete a server, use the trash icon on the Plugins page. The settings dialog has no delete button.

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. See Agents.