Notion (MCP)

Community Contribution

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.

Notion hosts a remote MCP server at https://mcp.notion.com/mcp that Open WebUI connects to natively via Streamable HTTP. Authentication is handled through Notion's OAuth flow: no API tokens, no proxies, no extra containers.

Setup

Prerequisite: WEBUI_SECRET_KEY

You MUST set the WEBUI_SECRET_KEY environment variable to a persistent value. Without it, your OAuth session breaks every time the container restarts, forcing re-authentication. See the MCP feature docs for details.

1. Add the tool

Go to Settings → Admin → Tools → Integrations and click + to add a new connection. Fill in the following:

Field	Value
Type	MCP Streamable HTTP
URL	https://mcp.notion.com/mcp
Auth	OAuth 2.1
ID	ntn
Name	Notion

Click Register Client, then Save. Use OAuth 2.1 (Static) if you have pre-created OAuth client credentials.

Alternative: Import JSON

You can also click Import in the modal and paste this 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": "Search, read, create, and manage Notion pages and databases."
    }
  }
]

2. Authorize

In any chat, open + → Integrations → Tools and toggle Notion on. You'll be redirected to Notion's OAuth flow. Select your workspace and grant access.

OAuth 2.1 tools cannot be pre-enabled

Do not set this as a default tool on a model. OAuth 2.1 requires an interactive browser redirect that cannot happen mid-request. Users must enable it manually per-chat via the + button. See MCP docs for details.

Re-authentication

Notion's OAuth session may expire after inactivity or container restarts. If you see Failed to connect to MCP server 'ntn', re-toggle the tool in any chat to trigger the authorization flow again.

Rate limits

Standard Notion API limits apply:

• General: 180 requests per minute
• Search: 30 requests per minute

Troubleshooting

Failed to connect to MCP server 'ntn'

Your OAuth session has expired. Re-toggle the Notion tool in any chat (+ → Integrations → Tools) to re-authorize.

OAuth callback failed: mismatching_state

You're accessing Open WebUI via localhost, but WEBUI_URL is set to a public domain. Access your instance using the exact URL from WEBUI_URL and authorize again.

Object not found

The page hasn't been shared with the integration. During the OAuth flow, Notion asks which pages to grant access to, so make sure the relevant pages are selected. You can update access anytime from your Notion integrations settings.

missing_property when creating a page

Notion requires a parent page or database. Tell the model: "Search for my 'Notes' page first, then create the new page inside it."