> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-cookbook-generated-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you to extend the agent's capabilities with custom tools.

## Overview

Model Context Protocol (MCP) is a mechanism that allows OpenHands to communicate with external tool servers. These
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

OpenHands supports the following MCP transport protocols:

* [Server-Sent Events (SSE)](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse)
* [Streamable HTTP (SHTTP)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)
* [Standard Input/Output (stdio)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)

## How MCP Works

When a conversation starts, OpenHands:

1. Reads the MCP servers you have configured and enabled.
2. Connects to any configured SSE and SHTTP servers.
3. Starts any configured stdio servers.
4. Registers the tools provided by these servers with the agent.

The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:

1. OpenHands routes the call to the appropriate MCP server.
2. The server processes the request and returns a response.
3. OpenHands converts the response to an observation and presents it to the agent.

Servers you add or change apply to new conversations, not to conversations that are already running.

## Configuration

Where you configure MCP servers depends on how you run OpenHands:

* **Agent Canvas** (local or connected to OpenHands Cloud): `Customize > MCP Servers`. See [Add a Custom Server](#add-a-custom-server).
* **CLI**: `openhands mcp add`, which writes `~/.openhands/mcp.json`. See [CLI MCP Servers](/openhands/usage/cli/mcp-servers).
* **SDK**: pass `mcp_config` to your agent. See the [SDK MCP Guide](/sdk/guides/mcp).

<Warning>
  Current OpenHands releases don't read MCP servers from a `config.toml` `[mcp]` section (`sse_servers`,
  `shttp_servers`, `stdio_servers`). That format belongs to legacy OpenHands (V0). If you still have one, add those
  servers again using one of the options above. The legacy format is kept for reference in the
  [V0 configuration options](/openhands/usage/v0/advanced/V0_configuration-options#mcp-configuration).
</Warning>

### Add a Custom Server

To add a server that isn't in the `Marketplace`:

1. In Agent Canvas, open `Customize > MCP Servers`.
2. Click `Add custom server`.
3. Choose a `Server Type` and fill in the fields for that type (see below).
4. Click `Test connection`. A working server reports how many tools it provides.
5. Save the server. New conversations can use its tools.

<Note>
  On a local backend, Agent Canvas saves MCP servers in its settings store (by default `~/.openhands/settings.json`)
  with credentials encrypted. Manage servers from `Customize > MCP Servers` rather than editing that file. There is no
  per-project MCP configuration file.
</Note>

### Server Fields

<Tabs>
  <Tab title="SHTTP">
    Streamable HTTP is the recommended transport for remote servers.

    * `Server name`: A name for the server.
    * `URL` (required): The server's endpoint, starting with `http://` or `https://`.
    * `Authentication`: How OpenHands authenticates to the server.
      * `None`: No credentials.
      * `Bearer token`: Enter the token in `API Key`. OpenHands sends `Authorization: Bearer <token>`.
      * `Header`: Enter custom headers in `Headers`, one `NAME=value` per line (for example, `X-API-Key=value`).
      * `OAuth`: See [OAuth Authentication](#oauth-authentication).
    * `Timeout (seconds)` (optional): How long to wait for the server before timing out. Use a longer timeout for
      servers whose tools run heavy operations such as large file processing.
  </Tab>

  <Tab title="SSE">
    Server-Sent Events is an older transport for remote servers. Use it only if the server doesn't support SHTTP.

    * `Server name`: A name for the server.
    * `URL` (required): The server's SSE endpoint.
    * `Authentication`: The same options as SHTTP.
  </Tab>

  <Tab title="STDIO">
    <Note>
      While stdio servers are supported, [we recommend using MCP proxies](#configuration-examples) for
      better reliability and performance.
    </Note>

    * `Name` (required): A unique name for the server. Accepted characters are letters, digits, underscores (`_`),
      and hyphens (`-`). For example, `integrations-hub` is a valid name.
    * `Command` (required): The command to run the server, such as `npx` or `uvx`.
    * `Command Arguments` (optional): One argument per line, passed to the command in order.
    * `Environment Variables` (optional): One `KEY=value` per line, set for the server process.
  </Tab>
</Tabs>

#### When to Use Direct Stdio

Direct stdio connections may still be appropriate in these scenarios:

* **Development and testing**: Quick prototyping of MCP servers.
* **Simple, single-use tools**: Tools that don't require high reliability or concurrent access.
* **Local-only environments**: When you don't want to manage additional proxy processes.

### Configuration Examples

<Tabs>
  <Tab title="Proxy Servers (SSE/HTTP) - Recommended">
    For stdio-based MCP servers, we recommend using MCP proxy tools like
    [`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
    [SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
    HTTP/SSE endpoints.

    Start the proxy servers separately:

    ```bash theme={null}
    # Terminal 1: Filesystem server proxy
    supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080

    # Terminal 2: Fetch server proxy
    supergateway --stdio "uvx mcp-server-fetch" --port 8081
    ```

    Then add each proxy with `Add custom server`:

    | Field | Filesystem proxy | Fetch proxy |
    | - | - | - |
    | `Server Type` | `SSE` | `SSE` |
    | `Server name` | `filesystem` | `fetch` |
    | `URL` | `http://localhost:8080/sse` | `http://localhost:8081/sse` |
    | `Authentication` | `None` | `None` |

    <Note>
      `localhost` works when the agent server runs on the same machine as the proxy. If your conversations run in
      Docker or a remote sandbox, use an address that environment can reach.
    </Note>
  </Tab>

  <Tab title="Direct Stdio Servers">
    <Note>
      This setup is not recommended for production.
    </Note>

    Add the server with `Add custom server`:

    | Field | Value |
    | - | - |
    | `Server Type` | `STDIO` |
    | `Name` | `fetch` |
    | `Command` | `uvx` |
    | `Command Arguments` | `mcp-server-fetch` |

    For production use, we recommend using proxy tools like SuperGateway.
  </Tab>
</Tabs>

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.

### Documenting an Integration for OpenHands

If you maintain an MCP server and want to publish setup steps for OpenHands users:

* For Agent Canvas, give the `Add custom server` values: `Server Type`, then `URL` and `Authentication` (SSE/SHTTP)
  or `Name`, `Command`, `Command Arguments`, and `Environment Variables` (STDIO).
* For the CLI, give the `openhands mcp add` command. See [CLI MCP Servers](/openhands/usage/cli/mcp-servers).
* Don't write a `config.toml` `[mcp]` section. Current OpenHands releases ignore it.
* To give the agent standing instructions (for example, when to call your tools), add them to the repository's
  `AGENTS.md`. OpenHands loads it into the agent's context. See [Repository Skills](/overview/skills/repo).

## Manage Installed Servers

In Agent Canvas, open `Customize > MCP Servers` to manage installed MCP servers. Use the control on an installed server card to disable it without deleting its configuration or saved credentials. Disabled servers are unavailable to new conversations until you enable them again.

Adding, editing, renaming, or deleting one server does not remove saved credentials for your other servers. Use the editor's delete action only when you want to remove that server configuration. Editing a disabled server does not enable it.

## 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

On OpenHands Cloud, saving MCP settings keeps the OAuth credential and its token state instead of flattening it into a request header, so installed servers keep their authorization across saves. When a server already holds working tokens, OpenHands probes them and skips the consent prompt; the browser window only opens when authorization is actually required.

### Configuration

<Tabs>
  <Tab title="Agent Canvas">
    Servers in the `Marketplace` that use OAuth, such as Notion, start the authorization flow when you install them.

    For a custom server, click `Add custom server`, choose `SHTTP` or `SSE`, and set `Authentication` to `OAuth`.
    Fill in `OAuth client ID`, `OAuth client secret`, and `OAuth scopes` if the server requires them.
  </Tab>

  <Tab title="CLI">
    Use the `--auth oauth` flag when adding an MCP server:

    ```bash theme={null}
    openhands mcp add notion --transport http \
      --auth oauth \
      https://mcp.notion.com/mcp
    ```

    This creates a configuration in `~/.openhands/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "notion": {
          "url": "https://mcp.notion.com/mcp",
          "transport": "http",
          "auth": "oauth"
        }
      }
    }
    ```
  </Tab>

  <Tab title="SDK">
    Configure OAuth in your `mcp_config`:

    ```python theme={null}
    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>
</Tabs>

<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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.