diff --git a/openhands/usage/settings/mcp-settings.mdx b/openhands/usage/settings/mcp-settings.mdx
index bf2d3956..b43c4827 100644
--- a/openhands/usage/settings/mcp-settings.mdx
+++ b/openhands/usage/settings/mcp-settings.mdx
@@ -192,3 +192,80 @@ Other options include:
 - **Custom FastAPI/Express servers**: Build your own HTTP wrapper around stdio MCP servers.
 - **Docker-based proxies**: Containerized solutions for better isolation.
 - **Cloud-hosted MCP services**: Third-party services that provide MCP endpoints.
+
+## OAuth Authentication
+
+Some MCP servers (like Notion MCP) require OAuth authentication instead of API keys. OpenHands supports OAuth-based MCP servers through the [FastMCP](https://gofastmcp.com/) library.
+
+### How OAuth Works
+
+When you configure an OAuth-enabled MCP server:
+
+1. **First connection**: When the agent first attempts to use tools from an OAuth-protected MCP server, OpenHands initiates the OAuth flow
+2. **Browser authentication**: A browser window opens automatically for you to authorize access
+3. **Token storage**: After authorization, tokens are securely stored locally in `~/.fastmcp/oauth-mcp-client-cache/`
+4. **Automatic refresh**: FastMCP automatically refreshes tokens as needed
+
+### Configuration
+
+<Tabs>
+  <Tab title="CLI">
+    Use the `--auth oauth` flag when adding an MCP server:
+
+    ```bash
+    openhands mcp add notion --transport http \
+      --auth oauth \
+      https://mcp.notion.com/mcp
+    ```
+
+    This creates a configuration in `~/.openhands/mcp.json`:
+    ```json
+    {
+      "mcpServers": {
+        "notion": {
+          "url": "https://mcp.notion.com/mcp",
+          "transport": "http",
+          "auth": "oauth"
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab title="SDK">
+    Configure OAuth in your `mcp_config`:
+
+    ```python
+    mcp_config = {
+        "mcpServers": {
+            "Notion": {
+                "url": "https://mcp.notion.com/mcp",
+                "auth": "oauth"
+            }
+        }
+    }
+    agent = Agent(llm=llm, tools=tools, mcp_config=mcp_config)
+    ```
+
+    See the [SDK MCP Guide](/sdk/guides/mcp) for complete examples.
+  </Tab>
+  <Tab title="Config File">
+    Add the `auth` field to your server configuration:
+
+    ```toml
+    [mcp]
+    shttp_servers = [
+        {url = "https://mcp.notion.com/mcp", auth = "oauth"}
+    ]
+    ```
+  </Tab>
+</Tabs>
+
+### Supported OAuth MCP Servers
+
+| Server | URL | Description |
+|--------|-----|-------------|
+| Notion | `https://mcp.notion.com/mcp` | Access Notion workspaces, pages, and databases |
+
+<Note>
+OAuth MCP servers require user interaction for the initial authentication. This means they may not be suitable for fully automated/headless workflows. For automation, consider using API key-based authentication where available.
+</Note>
diff --git a/overview/model-context-protocol.mdx b/overview/model-context-protocol.mdx
index cb6d0cf4..eaebd444 100644
--- a/overview/model-context-protocol.mdx
+++ b/overview/model-context-protocol.mdx
@@ -55,5 +55,6 @@ When OpenHands starts, it:
 ## Getting Started with MCP
 
 - **For detailed configuration**: See [MCP Settings](/openhands/usage/settings/mcp-settings)
+- **For CLI usage**: See [CLI MCP Servers](/openhands/usage/cli/mcp-servers)
 - **For SDK integration**: See [SDK MCP Guide](/sdk/guides/mcp)
 - **For architecture details**: See [MCP Architecture](/sdk/arch/mcp)
\ No newline at end of file
diff --git a/sdk/guides/mcp.mdx b/sdk/guides/mcp.mdx
index 15d3f980..531458cf 100644
--- a/sdk/guides/mcp.mdx
+++ b/sdk/guides/mcp.mdx
@@ -59,8 +59,8 @@ For MCP servers requiring OAuth authentication:
 - Configure OAuth-enabled MCP servers by specifying the URL and auth type
 - The SDK automatically handles the OAuth flow when first connecting
 - When the agent first attempts to use an OAuth-protected MCP server's tools, the SDK initiates the OAuth flow via [FastMCP](https://gofastmcp.com/servers/auth/authentication)
-- User will be prompted to authenticate
-- Access tokens are securely stored and automatically refreshed by FastMCP as needed
+- User will be prompted to authenticate via browser
+- Access tokens are securely stored in `~/.fastmcp/oauth-mcp-client-cache/` and automatically refreshed by FastMCP as needed
 
 ```python mcp_config focus={5} icon="python" wrap
 mcp_config = {
@@ -73,6 +73,10 @@ mcp_config = {
 }
 ```
 
+<Note>
+OAuth MCP servers require user interaction for the initial browser-based authentication. This means they are not suitable for fully automated/headless workflows. If you need headless access, check if the MCP provider offers API key authentication as an alternative.
+</Note>
+
 ## Ready-to-Run Basic MCP Usage Example
 
 <Note>