Skip to main content

​
Overview

Model Context Protocol (MCP) servers provide additional tools and context to OpenHands agents. You can add HTTP/SSE servers with authentication or stdio-based local servers to extend what OpenHands can do. The CLI provides two ways to manage MCP servers:
  1. CLI commands (openhands mcp) - Manage servers from the command line
  2. Interactive command (/mcp) - View server status within a conversation
If you’re upgrading from a version before release 1.0.0, you’ll need to redo your MCP server configuration as the format has changed from TOML to JSON.

​
MCP Commands

​
List Servers

View all configured MCP servers: 
openhands mcp list

​
Get Server Details

View details for a specific server: 
openhands mcp get <server-name>

​
Remove a Server

Remove a server configuration: 
openhands mcp remove <server-name>

​
Enable/Disable Servers

Control which servers are active: 
# Enable a server
openhands mcp enable <server-name>

# Disable a server
openhands mcp disable <server-name>

​
Adding Servers

​
HTTP/SSE Servers

Add remote servers with HTTP or SSE transport: 
openhands mcp add <name> --transport http <url>

​
With Bearer Token Authentication

openhands mcp add my-api --transport http \
  --header "Authorization: Bearer your-token" \
  https://api.example.com/mcp

​
With API Key Authentication

openhands mcp add weather-api --transport http \
  --header "X-API-Key: your-api-key" \
  https://weather.api.com

​
With Multiple Headers

openhands mcp add secure-api --transport http \
  --header "Authorization: Bearer token123" \
  --header "X-Client-ID: client456" \
  https://api.example.com

​
With OAuth Authentication

openhands mcp add notion-server --transport http \
  --auth oauth \
  https://mcp.notion.com/mcp

​
Stdio Servers

Add local servers that communicate via stdio: 
openhands mcp add <name> --transport stdio <command> -- [args...]

​
Basic Example

openhands mcp add local-server --transport stdio \
  python -- -m my_mcp_server

​
With Environment Variables

openhands mcp add local-server --transport stdio \
  --env "API_KEY=secret123" \
  --env "DATABASE_URL=postgresql://localhost/mydb" \
  python -- -m my_mcp_server --config config.json

​
Add in Disabled State

openhands mcp add my-server --transport stdio --disabled \
  node -- my-server.js

​
Command Reference

openhands mcp add <name> --transport <type> [options] <target> [-- args...]
OptionDescription
--transportTransport type: http, sse, or stdio (required)
--headerHTTP header for http/sse (format: "Key: Value", repeatable)
--envEnvironment variable for stdio (format: KEY=value, repeatable)
--authAuthentication method (e.g., oauth)
--enabledEnable immediately (default)
--disabledAdd in disabled state

​
Example: Web Search with Tavily

Add web search capability using Tavily’s MCP server: 
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"

​
Manual Configuration

You can also manually edit the MCP configuration file at ~/.openhands/mcp.json.

​
Configuration Format

The file uses the MCP configuration format: 
{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

​
Example Configuration

{
  "mcpServers": {
    "tavily-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tavily.com/mcp/?tavilyApiKey=your-api-key"
      ]
    },
    "local-tools": {
      "command": "python",
      "args": ["-m", "my_mcp_tools"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

​
Interactive /mcp Command

Within an OpenHands conversation, use /mcp to view server status:
  • View active servers: Shows which MCP servers are currently active in the conversation
  • View pending changes: If mcp.json has been modified, shows which servers will be mounted when the conversation restarts
The /mcp command is read-only. Use openhands mcp commands to modify server configurations.

​
Workflow

  1. Add servers using openhands mcp add
  2. Start a conversation with openhands
  3. Check status with /mcp inside the conversation
  4. Use the tools provided by your MCP servers
The agent will automatically have access to tools provided by enabled MCP servers.

​
Troubleshooting

​
Server Not Appearing

  1. Verify the server is enabled: 
    openhands mcp list
  2. Check the configuration: 
    openhands mcp get <server-name>
  3. Restart the conversation to load new configurations

​
Server Fails to Start

  1. Test the command manually: 
    # For stdio servers
python -m my_mcp_server

# For HTTP servers, check the URL is reachable
curl https://api.example.com/mcp
  2. Check environment variables and credentials
  3. Review error messages in the CLI output

​
Configuration File Location

The MCP configuration is stored at:
  • Config file: ~/.openhands/mcp.json

​
See Also