From f1d6906eb74e47f99c19680b37380430a9c21010 Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Thu, 27 Nov 2025 04:50:20 -0500 Subject: [PATCH 1/3] docs: Notion MCP refac --- docs/tutorials/integrations/mcp-notion.mdx | 130 ++++----------------- 1 file changed, 25 insertions(+), 105 deletions(-) diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index deb5ecbad..0cbc350ef 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -21,10 +21,14 @@ This tutorial is a community contribution and is not supported by the Open WebUI ## Prerequisites -Regardless of the connection method chosen, you must first create an internal integration within Notion. +:::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. +::: + +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. Create Internal Integration -1. Navigate to [Notion My Integrations](https://www.notion.so/my-integrations). +1. Navigate to **[Notion My Integrations](https://www.notion.so/my-integrations)**. 2. Click the **+ New integration** button. 3. Fill in the required fields: * **Integration Name:** Give it a recognizable name (e.g., "Open WebUI MCP"). @@ -50,9 +54,9 @@ Once saved, you will be directed to the configuration page. 3. Click **Save changes** if you modified any capabilities. :::warning Security: Risk to Workspace Data -While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk** to your data. +While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk**. -**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content** in this step. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages. +**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content**. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages. ::: :::danger Secret Safety @@ -246,7 +250,7 @@ If you are using **Method 1 (Streamable HTTP)**, you must perform the On-Demand :::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, revist steps 1-4 of this option to complete the "Connect with Notion MCP" authorization flow again, which will refresh your session. +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) @@ -260,7 +264,7 @@ You can configure a specific model to have Notion access enabled by default for 4. Check the box for **Notion**. 5. Click **Save & Update**. -## Best Practice: Create a Notion Agent +## Building a Specialized Notion Agent For the most reliable experience, we recommend creating a dedicated "Notion Assistant" model. This allows you to provide a specialized **System Prompt**, a helpful **Knowledge Base**, and quick-start **Prompt Suggestions** that teaches the model how to navigate Notion's structure. @@ -335,7 +339,6 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to ``` - 7. **Attach Knowledge Base:** * In the **Knowledge** section, click **Select Knowledge**. * In the modal that appears, find and select the **Notion MCP Docs** knowledge base you created in Step 1. @@ -343,7 +346,7 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to :::warning Performance Tuning While the knowledge base helps the model understand Notion's capabilities, injecting large amounts of documentation can sometimes interfere with tool calling on smaller models (overloading the context). -If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above or use your own custom system prompt. +If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above. ::: 8. **Add Prompt Suggestions:** @@ -362,99 +365,15 @@ Under the **Prompts** section, click the **+** button to add a few helpful start ![Model Creation Screen: Shows the model settings with Name 'Notion Assistant', description, and the Notion System Prompt filled out.](/images/mcp-notion/notion-setup-step11.png) -## Supported Tools & Usage - -Once enabled, the model will have access to a powerful suite of tools to manage your Notion workspace. The server automatically handles converting Notion's block-based structure into Markdown for the AI, and converts the AI's Markdown back into Notion blocks. +## Supported Tools :::tip Workflow Best Practice LLMs cannot "browse" Notion like a human. For most actions, the model first needs to know the **Page ID or URL**. Always ask the model to **search** for a page first before asking it to read or modify it. ::: -## šŸ”Ž Search & Retrieval - -- **`notion-search`** ā€“ Fullā€‘text / metadata search across Notion (and linked tools) - - **Input:** query string (e.g., `ready for dev`) - - **Returns:** list of object IDs + brief metadata - - **Prompt example:** ā€œFind all project pages that mention **ā€˜ready for devā€™**.ā€ - - **Note:** IDs returned here are required for almost every other command. - -- **`notion-fetch`** *(aka `read-page`)* ā€“ Pull a page or database content by URL or ID - - **Input:** page/database URL **or** ID - - **Returns:** Markdownā€‘formatted content of the page/database - - **Prompt example:** ā€œWhat are the product requirements from this ticket `https://notion.so/page-url`?ā€ - - **Note:** Gives you a clean Markdown view, ready for further processing. - -## šŸ› ļø Content Management - -- **`notion-create-pages`** ā€“ Create a brandā€‘new page - - **Input:** parent pageā€ÆID, title, property map, body (Markdown format) - - **Returns:** new page ID & URL - - **Prompt example:** ā€œCreate a meetingā€‘notes page for todayā€™s standā€‘up with action items.ā€ - - **Key:** **Parent page ID is mandatory**. - -- **`notion-update-page`** ā€“ Patch a pageā€™s **properties** (status, tags, dates, etc.) - - **Input:** pageā€ÆID + property map - - **Returns:** updated page object - - **Prompt example:** ā€œChange the status of this task from **ā€˜In Progressā€™** to **ā€˜Completeā€™**.ā€ - - **Key:** Does **not** edit the pageā€™s body blocks. - -- **`notion-append-block`** ā€“ Add a block (text, checklist, heading, etc.) to the end of a page - - **Input:** pageā€ÆID + block payload (JSON format) - - **Returns:** updated page version - - **Prompt example:** ā€œAdd a checklist item to the bottom of the shoppingā€‘list page.ā€ - -- **`notion-move-pages`** ā€“ Move one or many pages/databases under a new parent - - **Input:** source page/database ID(s) + destination parent ID - - **Returns:** new parent relationship (page now lives under the target) - - **Prompt example:** ā€œMove my weekly meetingā€‘notes page to the **ā€˜Team Meetingsā€™** page.ā€ - -- **`notion-duplicate-page`** ā€“ Clone a page (asynchronous ā€“ returns a job ID) - - **Input:** source pageā€ÆID (optional target parent) - - **Returns:** job ID ā†’ duplicated page ID once the job finishes - - **Prompt example:** ā€œDuplicate my projectā€‘template page for the new Q3 initiative.ā€ - -## šŸ“Š Database Management - -- **`notion-create-database`** ā€“ Spin up a new database with a custom schema - - **Input:** parent pageā€ÆID, title, property definitions (type, name, options) - - **Returns:** new database ID & URL - - **Prompt example:** ā€œCreate a database to track customer feedback with fields for **name**, **priority**, and **status**.ā€ - -- **`notion-update-database`** ā€“ Alter a databaseā€™s schema (add/rename fields) or rename the DB itself - - **Input:** databaseā€ÆID + schema changes (add property, rename, etc.) - - **Returns:** updated database object - - **Prompt example:** ā€œAdd a **ā€˜Statusā€™** field to our project database to track completion.ā€ - -## šŸ’¬ Collaboration & Workspace - -- **`notion-create-comment`** ā€“ Post a comment on a page - - **Input:** pageā€ÆID + comment text - - **Returns:** comment ID & timestamp - - **Prompt example:** ā€œLeave a note on the quarterly review page about budget concerns.ā€ - -- **`notion-get-comments`** ā€“ List every comment on a page (supports pagination) - - **Input:** pageā€ÆID - - **Returns:** array of comment objects - - **Prompt example:** ā€œList all comments on the projectā€‘requirements section.ā€ - -- **`notion-get-users`** ā€“ Fetch **all** workspace members - - **Input:** *(none)* - - **Returns:** array of user objects - - **Prompt example:** ā€œWho are the members of this workspace?ā€ - -- **`notion-get-user`** ā€“ Get a single userā€™s profile (by ID or email) - - **Input:** userā€ÆID or email address - - **Returns:** user object (name, avatar, email, etc.) - - **Prompt example:** ā€œLook up the profile of the person assigned to this task.ā€ - -- **`notion-get-teams`** ā€“ Retrieve all **teamspaces** (formerly ā€œteamsā€) in the workspace - - **Input:** *(none)* - - **Returns:** array of team objects - -- **`notion-get-self`** ā€“ Information about the bot itself and the workspace itā€™s linked to - - **Input:** *(none)* - - **Returns:** bot metadata + workspace metadata (ID, name, domain, etc.) - - **Prompt example:** ā€œWhich Notion workspace am I currently connected to?ā€ +This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases. + +For a complete list of available tools, their schemas, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**. ## Rate Limits Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls. @@ -468,7 +387,9 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa ## Troubleshooting -### Error: `Failed to connect to MCP server 'ntn'` +### Connection Errors + +#### `Failed to connect to MCP server 'ntn'` ![MCP Connection Error: Shows a red error message in the chat 'Failed to connect to MCP server 'ntn'.](/images/mcp-notion/notion-setup-step12.png) @@ -480,27 +401,26 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa 4. This will trigger the redirect to Notion's authorization page to complete the "Connect with Notion MCP" authorization flow again. 5. Once authorized successfully, the connection will work across all chats again, including for models with the tool enabled by default. -### Error: `OAuth callback failed: mismatching_state` - +#### `OAuth callback failed: mismatching_state` ![OAuth Error Toast: Shows the red error notification 'OAuth callback failed: mismatching_state: CSRF Warning! State not equal in request and response'.](/images/mcp-notion/notion-setup-step13.png) -If you receive this red error toast when registering the client or connecting via the tool toggle, it is likely due to a URL mismatch. - * **Cause:** You are likely accessing Open WebUI via `localhost` (e.g., `http://localhost:3000`), but your instance is configured with a public domain via the `WEBUI_URL` environment variable (e.g., `https://chat.mydomain.com`). The OAuth session state created on `localhost` is lost when the callback redirects to your public domain. * **Fix:** Access your Open WebUI instance using the **exact URL** defined in `WEBUI_URL` (your public domain) and perform the setup again. **Do not use `localhost` for OAuth setups if a domain is configured.** -### Error: `Object not found` +### Usage Errors + +#### `Object not found` * **Cause:** The Integration Token is valid, but the specific page has not been shared with the integration. * **Fix:** In Notion, go to your Integration settings > **Access** tab and ensure the page is checked, or visit the page directly and check the **Connections** menu to ensure your integration is listed and selected. -### Error: `Tool execution failed` (Local Method) +#### `Tool execution failed` (Local Method) * **Cause:** Open WebUI is unable to execute the local command (npx/docker) because it is missing from the container, or the configuration is incorrect. * **Fix:** Native local execution is not supported. Ensure you are using **MCPO** (Method 2) to bridge these commands, rather than entering them directly into Open WebUI's config, or switch to **Method 1 (Streamable HTTP)** in the Configuration section above. This runs on Notion's servers and requires no local dependencies. -### Error: `missing_property` when creating a page +#### `missing_property` when creating a page * **Cause:** The model is trying to create a page without specifying a **Parent ID**. Notion requires every page to exist inside another page or database. * **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."* -### Error: `RateLimitedError` (429) +#### `RateLimitedError` (429) * **Cause:** You have exceeded Notion's API limits (approx. 3 requests/second). * **Fix:** Ask the model to perform actions sequentially rather than all at once (e.g., "Search for X, then wait, then search for Y"). From 8cf906925fcdc18470a44d2cc0fd110dabfd44a1 Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Thu, 27 Nov 2025 04:53:27 -0500 Subject: [PATCH 2/3] wording --- docs/tutorials/integrations/mcp-notion.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index 0cbc350ef..80c2756bf 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -373,7 +373,7 @@ LLMs cannot "browse" Notion like a human. For most actions, the model first need This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases. -For a complete list of available tools, their schemas, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**. +For a complete list of available tools, their descriptions, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**. ## Rate Limits Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls. From 1719934e103ee986ee5cecfbf15b9793d242f607 Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Thu, 27 Nov 2025 06:16:02 -0500 Subject: [PATCH 3/3] docs: Notion MCP refactor --- docs/tutorials/integrations/mcp-notion.mdx | 335 ++++++++++----------- 1 file changed, 163 insertions(+), 172 deletions(-) diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index 80c2756bf..c3444718a 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. 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 Internal Integration +### 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. - -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) +## Configuration: Always On (Optional) -### 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.