Add the KnowMan server in OpenHands
In Agent Canvas, whether local or connected to OpenHands Cloud, MCP servers live under Customize > MCP Servers. Click "Add custom server", choose a Server Type, and fill in its fields (OpenHands docs).
For KnowMan, choose the STDIO type. Set Name to knowman. Name allows letters, digits, underscore and hyphen. Set Command to npx, a typical launcher for this field, and enter -y and @knowman/mcp as Command Arguments, one per line, passed in order. Under Environment Variables, add one line, KNOWMAN_API_KEY=km_... (OpenHands docs). The @knowman/mcp package runs on Node 22 or newer (npm).
Sign in once with knowman login
You can skip the API key line entirely. The same package installs a CLI named knowman. Run npx -p @knowman/mcp knowman login once, sign in in the browser, and the saved credential is shared by the CLI and the MCP server, so the environment variable block can be dropped (knowman-mcp on GitHub).
If you prefer a key, create one in the web app at Settings > Connections > Connect an AI agent. Keys look like km_... (npm).
Verify the connection
Click "Test connection". A working server reports how many tools it provides (OpenHands docs). KnowMan provides six tools (npm). Then save the server. New conversations can use its tools, because changes apply to new conversations only, not running ones (OpenHands docs).
Where OpenHands stores MCP servers
On a local backend, servers are saved in the settings store, by default ~/.openhands/settings.json, with encrypted credentials (OpenHands docs). There is no per-project MCP config file. OpenHands advises managing servers from the UI rather than editing that file directly. From Customize > MCP Servers you can also disable a server without deleting its configuration or saved credentials (OpenHands docs).
Common problems
OpenHands labels direct stdio as not recommended for production. It may suit prototyping, simple single-use tools, or local-only setups. For stdio servers, OpenHands recommends a proxy such as SuperGateway, which exposes stdio MCP servers as HTTP/SSE endpoints. If conversations run in Docker or a remote sandbox, use an address that environment can reach, since localhost only works when the agent server runs on the same machine as the proxy (OpenHands docs).
On the KnowMan side, if KNOWMAN_API_KEY is missing, the server exits with a message on stderr (npm).
What the KnowMan server can do
The server exposes six tools (npm). kb_search searches saved items by keyword or meaning and returns titles, URLs and metadata. kb_ask answers questions with citations. kb_get_item returns the readable content of one item.
kb_save saves a URL to the Inbox or the Knowledge Base with an optional note. kb_recent lists recent items. kb_memories lists saved claims, decisions and playbooks. For background, see the KnowMan MCP server guide.
Use KnowMan in a conversation
When a conversation starts, OpenHands reads your enabled MCP servers, connects to SSE and SHTTP servers, starts stdio servers, and registers their tools with the agent (OpenHands docs). Ask the assistant to search or save, for example "search my KnowMan for ..." or "save this URL" (knowman-mcp on GitHub). For the wider picture, see knowledge bases for AI agents.
Questions people ask
Does OpenHands support stdio MCP servers?
Yes. OpenHands supports SSE, Streamable HTTP (SHTTP), and stdio transports, though proxies are recommended for stdio (OpenHands docs). Direct stdio is labeled not recommended for production and may suit prototyping, simple single-use tools, or local-only setups (OpenHands docs).
Where does OpenHands store MCP server settings?
On a local backend, servers are saved in the settings store, by default ~/.openhands/settings.json, with encrypted credentials (OpenHands docs). There is no per-project MCP config file, and OpenHands advises managing servers from the UI rather than editing that file directly (OpenHands docs).
Do MCP changes apply to conversations that are already running?
No. Changes apply to new conversations only, not running ones (OpenHands docs). When a conversation starts, OpenHands connects to SSE and SHTTP servers, starts stdio servers, and registers their tools with the agent (OpenHands docs).