> ## Documentation Index > Fetch the complete documentation index at: https://docs.onyx.app/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Connect Model Context Protocol servers to Chat, custom agents, and Craft > [!NOTE] > > In Onyx 5.0, MCP servers moved from their own admin page to **Admin Panel → Plugins**. > See [Where things moved](/admins/plugins/overview#where-things-moved-in-onyx-5). An MCP plugin connects Onyx to a server that uses the [Model Context Protocol](https://modelcontextprotocol.io/). 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](/admins/plugins/craft_apps) exists for the application. > [!NOTE] > > To let other MCP clients use Onyx as a server, see [Onyx MCP Server](/overview/onyx_anywhere/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 Slack, HubSpot, Asana, Linear, Notion, Sentry, Atlassian, and Add custom MCP server](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/add_mcp_catalog.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=4bce9d2c809a9d8516c37a82219d0787) 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. **2. 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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_custom_filled.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=1fcff1e4f0e55ee5288a704f43779f5e) Catalog entries also show a **Setup guide** link to the vendor's documentation. ![The Add MCP Server dialog for Linear with OAuth detected](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_linear_setup.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=6486fb5cc928f4e6f556dd19077d18ca) The 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: | 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**. **4. Configure authentication** Select an **Authentication Method**. Onyx marks the method it detected as **Recommended**. See [Authentication](#authentication) for each method. ![The Authentication Method menu with OAuth, API Key, and No authentication](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_auth_methods.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=53ca7887dd96a3ae925d7ed27dcfb1f3) **5. 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](/overview/core_features/plugins). 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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_linear_oauth.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=1d81a6e742e29e583098546393edbe55) | 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: ```text theme={null} https:///mcp/oauth/callback ``` > [!WARNING] > > 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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_api_key.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=d0c38186ba1083b34dd7d29749d3c617) 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. ![Advanced settings with Custom Headers and Connection transport](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_advanced.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=3a56932d54576815b95e620354d4633a) * **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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_tab_tools.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=a421a60791cc60030b3245645ffecf79) * 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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_tools_approval.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=a756c2bddade5d015b4930299058c096) | 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. > [!WARNING] > > 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](https://mintcdn.com/danswer/yAnT-i7LBUiCJgOS/assets/admins/plugins/mcp_after_connect.png?fit=max\&auto=format\&n=yAnT-i7LBUiCJgOS\&q=85\&s=a2d12e03270d4930799c34ab7605394c) | 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](/admins/agents/overview). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.