# Add the KnowMan MCP server to OpenHands

Client: OpenHands

In OpenHands, open Customize > MCP Servers, click "Add custom server", pick the STDIO type, and set Command to npx, Command Arguments to -y and @knowman/mcp, and [Environment Variables](https://www.knowman.io/guides/mcp-server-knowledge-base) to KNOWMAN_API_KEY=km_... ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). Create the key in KnowMan at Settings > Connections > Connect an AI agent, or run `npx -p @knowman/mcp knowman login` once and skip the variable ([@knowman/mcp on npm](https://www.npmjs.com/package/@knowman/mcp)). Click "Test connection", save, and new conversations get KnowMan's six tools ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

## OpenHands STDIO server fields (Customize > MCP Servers)

```text
Server Type: STDIO
Name: knowman
Command: npx
Command Arguments:
-y
@knowman/mcp
Environment Variables:
KNOWMAN_API_KEY=km_...
```

## 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). The @knowman/mcp package runs on Node 22 or newer ([npm](https://www.npmjs.com/package/@knowman/mcp)).

## 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](https://www.knowman.io/guides/personal-knowledge-base) 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](https://github.com/Essatt/knowman-mcp)).

If you prefer a key, create one in the web app at Settings > Connections > Connect an AI agent. Keys look like km_... ([npm](https://www.npmjs.com/package/@knowman/mcp)).

## Verify the connection

Click "Test connection". A working server reports how many tools it provides ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). KnowMan provides six tools ([npm](https://www.npmjs.com/package/@knowman/mcp)). Then save the server. New conversations can use its tools, because changes apply to new conversations only, not running ones ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

## 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

## 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

On the KnowMan side, if KNOWMAN_API_KEY is missing, the server exits with a message on stderr ([npm](https://www.npmjs.com/package/@knowman/mcp)).

## What the KnowMan server can do

The server exposes six tools ([npm](https://www.npmjs.com/package/@knowman/mcp)). kb_search searches [saved items](https://www.knowman.io/guides/how-to-save-articles) by [keyword or meaning](https://www.knowman.io/guides/ai-knowledge-base) 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](https://www.knowman.io/guides/mcp-server-knowledge-base).

## 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). Ask the assistant to search or save, for example "search my KnowMan for ..." or "save this URL" ([knowman-mcp on GitHub](https://github.com/Essatt/knowman-mcp)). For the wider picture, see [knowledge bases for AI agents](https://www.knowman.io/guides/knowledge-base-for-ai-agents).

## Questions

### Does OpenHands support stdio MCP servers?

Yes. OpenHands supports SSE, Streamable HTTP (SHTTP), and stdio transports, though proxies are recommended for stdio ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). Direct stdio is labeled not recommended for production and may suit prototyping, simple single-use tools, or local-only setups ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

### 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](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). There is no per-project MCP config file, and OpenHands advises managing servers from the UI rather than editing that file directly ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

### Do MCP changes apply to conversations that are already running?

No. Changes apply to new conversations only, not running ones ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)). When a conversation starts, OpenHands connects to SSE and SHTTP servers, starts stdio servers, and registers their tools with the agent ([OpenHands docs](https://docs.openhands.dev/openhands/usage/settings/mcp-settings)).

## Related pages

- [Connect your knowledge base through KnowMan's MCP server](https://www.knowman.io/guides/mcp-server-knowledge-base)

- [What Is a Knowledge Base for AI Agents?](https://www.knowman.io/guides/knowledge-base-for-ai-agents)

- [How Do You Connect AI to Your Notes?](https://www.knowman.io/guides/connect-any-ai-to-your-notes)

- [How to Give Your AI Context from What You Read](https://www.knowman.io/guides/give-your-ai-context)

## More in this topic

- [Connect KnowMan to Claude Code](https://www.knowman.io/integrations/claude-code)
- [KnowMan MCP server for Codex](https://www.knowman.io/integrations/codex)
- [Connect KnowMan to Gemini CLI](https://www.knowman.io/integrations/gemini-cli)

## Give your agent your library

Try KnowMan Pro for 14 days with no credit card. [Create your account](https://app.knowman.io/signup)

[Start free](https://app.knowman.io/signup)

Every new account starts with 14 days of Pro. No credit card.

Source: https://www.knowman.io/integrations/openhands