Skip to content

docs: Add MCP OAuth authentication documentation #371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
neubig wants to merge 1 commit into
base: main
Choose a base branch
from
+84 −2
Draft

docs: Add MCP OAuth authentication documentation #371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions openhands/usage/settings/mcp-settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
servers can provide additional functionality to the agent, such as specialized data processing, external API access,
or custom tools. MCP is based on the open standard defined at [modelcontextprotocol.io](https://modelcontextprotocol.io).

## Supported MCPs

Check warning on line 13 in openhands/usage/settings/mcp-settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

openhands/usage/settings/mcp-settings.mdx#L13 

Did you really mean 'MCPs'?

OpenHands supports the following MCP transport protocols:

Expand Down Expand Up @@ -192,3 +192,80 @@
- **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>
1 change: 1 addition & 0 deletions overview/model-context-protocol.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
8 changes: 6 additions & 2 deletions sdk/guides/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand All @@ -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>
Expand Down