diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index 80c2756..c344471 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -19,15 +19,167 @@ This integration utilizes the official Notion MCP server, which specializes in * This tutorial is a community contribution and is not supported by the Open WebUI team. It serves as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/tips/contributing-tutorial/). ::: -## Prerequisites +## Method 1: Streamable HTTP (Recommended) -:::info Note for Streamable HTTP -If you plan to use **Method 1 (Streamable HTTP)**, the OAuth flow may handle the integration creation automatically. However, we highly recommend following the steps below regardless. This ensures you have granular control over page permissions and a valid **Internal Integration Secret** available for troubleshooting or manual configuration. +This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers. + +:::info Preferred Method +**Streamable HTTP** is preferred for its simplicity and enhanced security. It handles authentication via Notion's official OAuth flow, meaning you do not need to manually manage secrets or integration tokens. ::: -Regardless of the connection method chosen, you should create an internal integration within Notion to ensure you have the necessary credentials and permission scopes. +### 1. Configure Tool +You can automatically prefill the connection settings by importing the JSON configuration below. -### 1. Create Internal Integration +1. Navigate to **Admin Panel > Settings > External Tools**. +2. Click the **+** (Plus) button to add a new tool. +3. Click **Import** (top right of the modal). +4. Paste the following JSON snippet: + +```json title="Notion Remote MCP Configuration" +[ + { + "type": "mcp", + "url": "https://mcp.notion.com/mcp", + "spec_type": "url", + "spec": "", + "path": "openapi.json", + "auth_type": "oauth_2.1", + "key": "", + "info": { + "id": "ntn", + "name": "Notion", + "description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content." + } + } +] +``` + +5. **Register:** Click the **Register Client** button (next to the Auth dropdown). +6. Click **Save**. + +![Open WebUI Tool Config: Shows the External Tools modal with the JSON imported and Register Client button highlighted.](/images/mcp-notion/notion-setup-step5.png) + +### 2. Authenticate & Grant Access +Once the tool is added, you must authenticate to link your specific workspace. + +1. Open any chat window. +2. Click the **+** (Plus) button in the chat input bar. +3. Navigate to **Integrations > Tools**. +4. Toggle the **Notion** switch to **ON**. + +![Chat Interface Toggle: Shows the chat input bar with the '+' menu open, 'Integrations' selected, and the 'Notion' tool toggled ON.](/images/mcp-notion/notion-setup-step6.png) + +5. **Authorize:** You will be redirected to a "Connect with Notion MCP" screen. + * Ensure the correct **Workspace** is selected in the dropdown. + * Click **Continue**. + +:::note Security: Frequent Re-authentication +For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error. + +This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revisit the steps above to complete the "Connect with Notion MCP" authorization flow again. +::: + +![Notion OAuth Screen: Shows the 'Connect with Notion MCP' authorization page with the workspace dropdown selected.](/images/mcp-notion/notion-setup-step7.png) + +--- + +## Method 2: Self-Hosted via MCPO (Advanced) + +This method is for advanced users who prefer to run the MCP server locally within their own infrastructure using **MCPO**. Unlike Streamable HTTP, this method requires you to manually manage your own credentials. + +Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server locally (using Docker or Node.js) within your infrastructure, you must use **MCPO** to bridge the connection. + +:::info Prerequisites +To use this method, you must first create an internal integration to obtain a **Secret Key**. Please complete the **[Creating an Internal Integration](#creating-an-internal-integration)** section below before proceeding with the configuration steps here. +::: + +### 1. Configure MCPO +Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running. Configure your MCPO instance to run the Notion server using one of the runtimes below by adding the JSON block to your `mcpo-config.json` file. + +**Note:** Replace `secret_YOUR_KEY_HERE` with the secret obtained from the [Creating an Internal Integration](#creating-an-internal-integration) section. + + + + This configuration uses the official Node.js package. + + ```json title="mcpo-config.json" + { + "mcpServers": { + "notion": { + "command": "npx", + "args": [ + "-y", + "@notionhq/notion-mcp-server" + ], + "env": { + "NOTION_TOKEN": "secret_YOUR_KEY_HERE" + } + } + } + } + ``` + + + This configuration uses the official Docker image. + + ```json title="mcpo-config.json" + { + "mcpServers": { + "notion": { + "command": "docker", + "args": [ + "run", + "--rm", + "-i", + "-e", + "NOTION_TOKEN", + "mcp/notion" + ], + "env": { + "NOTION_TOKEN": "secret_YOUR_KEY_HERE" + } + } + } + } + ``` + + + +### 2. Connect Open WebUI +Once MCPO is running and configured with Notion: + +1. Navigate to **Admin Panel > Settings > External Tools**. +2. Click the **+** (Plus) button. +3. Click **Import** (top right of the modal). +4. Paste the following JSON snippet (update the URL with your MCPO address): + +```json title="MCPO Connection JSON" +[ + { + "type": "openapi", + "url": "http://:/notion", + "spec_type": "url", + "spec": "", + "path": "openapi.json", + "auth_type": "bearer", + "key": "", + "info": { + "id": "notion-local", + "name": "Notion (Local)", + "description": "Local Notion integration via MCPO" + } + } +] +``` +5. Click **Save**. + +--- + +## Creating an Internal Integration + +Required for **Method 2**, creating an internal integration within Notion ensures you have the necessary credentials and permission scopes readily available. + +### 1. Create Integration 1. Navigate to **[Notion My Integrations](https://www.notion.so/my-integrations)**. 2. Click the **+ New integration** button. 3. Fill in the required fields: @@ -45,7 +197,7 @@ You **must** select **Internal** for the integration type. Public integrations r ### 2. Configure Capabilities & Copy Secret Once saved, you will be directed to the configuration page. -1. **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for Open WebUI. +1. **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for MCPO configuration. 2. **Review Capabilities:** Ensure the following checkboxes are selected under the "Capabilities" section: * ✅ **Read content** * ✅ **Update content** @@ -65,10 +217,10 @@ Your **Internal Integration Secret** allows access to your Notion data. Treat it ![Notion Capabilities Config: Shows the Internal Integration Secret revealed and the three content capability checkboxes selected.](/images/mcp-notion/notion-setup-step2.png) -### 3. Grant Page Access +### 3. Grant Page Access (Manual) :::danger Critical Step: Permissions -By default, your new integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors. +By default, your new internal integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors. ::: You can grant access centrally or on a per-page basis. @@ -91,172 +243,11 @@ Still in the Notion Integration dashboard: ![Notion Page Connection: Shows a Notion page with the '...' menu open, the 'Connect' submenu active, and the integration being selected.](/images/mcp-notion/notion-setup-step4.png) -## Configuration +--- -There are two ways to connect Notion. We recommend **Streamable HTTP** for the easiest setup experience (OAuth), or **Local CLI** for advanced control using your integration token. +## Configuration: Always On (Optional) -The **Streamable HTTP** method is natively supported and recommended for most users for the easiest setup experience (OAuth). - -To run the server locally (using Docker or Node.js), you must use the **MCPO Bridge**. - - - - This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers. - - ### Quick Setup via Import - You can automatically prefill the connection settings by importing the JSON configuration below. - - 1. Navigate to **Admin Panel > Settings > External Tools**. - 2. Click the **+** (Plus) button to add a new tool. - 3. Click **Import** (top right of the modal). - 4. Paste the following JSON snippet: - - ```json title="Notion Remote MCP Configuration" - [ - { - "type": "mcp", - "url": "https://mcp.notion.com/mcp", - "spec_type": "url", - "spec": "", - "path": "openapi.json", - "auth_type": "oauth_2.1", - "key": "", - "info": { - "id": "ntn", - "name": "Notion", - "description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content." - } - } - ] - ``` - - 5. **Enter Key:** Paste your **Internal Integration Secret** (starts with `secret_`) into the "Key" field. - 6. **Register:** Click the **Register Client** button (next to the Auth dropdown). - 7. Click **Save**. - - ![Open WebUI Tool Config: Shows the External Tools modal with the JSON imported, Key pasted, and Register Client button highlighted.](/images/mcp-notion/notion-setup-step5.png) - - - - - Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server using `docker` or `npx` within your infrastructure, you must use **MCPO**. - - MCPO acts as a bridge, running your local commands and exposing them to Open WebUI via a local HTTP endpoint. - - ### Step 1: Deploy MCPO - Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running (usually done via Docker). - - ### Step 2: Configure MCPO - Configure your MCPO instance to run the Notion server using one of the runtimes below. Add the appropriate JSON block to your `mcpo-config.json` file. - - - - This configuration uses the official Node.js package. - - ```json title="mcpo-config.json" - { - "mcpServers": { - "notion": { - "command": "npx", - "args": [ - "-y", - "@notionhq/notion-mcp-server" - ], - "env": { - "NOTION_TOKEN": "secret_YOUR_KEY_HERE" - } - } - } - } - ``` - - - This configuration runs the server as an isolated container. - - ```json title="mcpo-config.json" - { - "mcpServers": { - "notion": { - "command": "docker", - "args": [ - "run", - "--rm", - "-i", - "-e", - "NOTION_TOKEN", - "mcp/notion" - ], - "env": { - "NOTION_TOKEN": "secret_YOUR_KEY_HERE" - } - } - } - } - ``` - - - - ### Step 3: Connect Open WebUI - Once MCPO is running and configured with Notion: - - 1. Navigate to **Admin Panel > Settings > External Tools**. - 2. Click the **+** (Plus) button. - 3. Click **Import** (top right of the modal). - 4. Paste the following JSON snippet (update the URL with your MCPO address): - - ```json title="MCPO Connection JSON" - [ - { - "type": "openapi", - "url": "http://:/notion", - "spec_type": "url", - "spec": "", - "path": "openapi.json", - "auth_type": "bearer", - "key": "", - "info": { - "id": "notion-local", - "name": "Notion (Local)", - "description": "Local Notion integration via MCPO" - } - } - ] - ``` - 5. Click **Save**. - - - -## Enabling the Tool - -After configuring the connection in the Admin Panel, you must enable the tool for the AI to use it. - -:::tip Initial Authentication -If you are using **Method 1 (Streamable HTTP)**, you must perform the On-Demand step below at least once to trigger the OAuth flow. If using **Method 2 (MCPO)**, authentication is handled by the API key in your configuration. -::: - -### Option 1: On-Demand (Per Chat) - -1. Open a new chat. -2. Click the **+** (Plus) button in the chat input bar. -3. Navigate to **Integrations > Tools**. -4. Toggle the **Notion** switch to **ON**. - -![Chat Interface Toggle: Shows the chat input bar with the '+' menu open, 'Integrations' selected, and the 'Notion' tool toggled ON.](/images/mcp-notion/notion-setup-step6.png) - -5. **Authorize:** (Method 1 Only) You will be redirected to a "Connect with Notion MCP" screen. - * Ensure the correct **Workspace** (the one you configured in step 1) is selected in the dropdown. - * Click **Continue**. - -:::note Security: Frequent Re-authentication -For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error. - -This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revisit steps 1-4 of this option to complete the "Connect with Notion MCP" authorization flow again. -::: - -![Notion OAuth Screen: Shows the 'Connect with Notion MCP' authorization page with the workspace dropdown selected.](/images/mcp-notion/notion-setup-step7.png) - -### Option 2: Always On (Model Default) -You can configure a specific model to have Notion access enabled by default for every conversation. +By default, users must toggle the tool **ON** in the chat menu. You can configure a specific model to have Notion access enabled by default for every conversation. 1. Go to **Workspace > Models**. 2. Click the **pencil icon** to edit a model.