From 62289129d877ebebfe7e17c635282f5a76a09aec Mon Sep 17 00:00:00 2001 From: Graham Neubig Date: Wed, 4 Mar 2026 05:37:02 -0500 Subject: [PATCH] docs: Add MCP OAuth authentication documentation - Add OAuth authentication section to MCP settings page explaining how OAuth works, configuration options (CLI, SDK, config file), and supported OAuth MCP servers (Notion) - Enhance SDK MCP guide with OAuth token storage path and headless workflow note - Document that OAuth tokens are stored in ~/.fastmcp/oauth-mcp-client-cache/ Co-authored-by: openhands --- openhands/usage/settings/mcp-settings.mdx | 77 +++++++++++++++++++++++ overview/model-context-protocol.mdx | 1 + sdk/guides/mcp.mdx | 8 ++- 3 files changed, 84 insertions(+), 2 deletions(-) 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 + + + + 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" + } + } + } + ``` + + + 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. + + + Add the `auth` field to your server configuration: + + ```toml + [mcp] + shttp_servers = [ + {url = "https://mcp.notion.com/mcp", auth = "oauth"} + ] + ``` + + + +### Supported OAuth MCP Servers + +| Server | URL | Description | +|--------|-----|-------------| +| Notion | `https://mcp.notion.com/mcp` | Access Notion workspaces, pages, and databases | + + +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. + 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 = { } ``` + +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. + + ## Ready-to-Run Basic MCP Usage Example