Connect an Existing Agent

If you already run OpenClaw, Hermes, Claude Code, or any other MCP-capable client, it can connect to your Companion Hub and Companion Memory directly — no Companion-built agent required.

Neither packaged agent app is a fork. The Companion OpenClaw app installs stock OpenClaw from npm, and the Companion Hermes app builds on the official Hermes Agent image — so the MCP surface they use is the same one your install can reach.

What the images add on top is a memory-slot provider plus some appliance plumbing. That provider is published separately for OpenClaw and Hermes, so your own install can have it too — see Beyond MCP: first-class memory.

What connecting gives you

Companion Hub and Companion Memory each expose a Model Context Protocol server over Streamable HTTP. Registering them gives your agent tools it can call — appliance management from Hub, and recall and capture from Memory.

MCP gives your agent tools. It does not give it a memory slot — passive turn capture and automatic context injection are a separate mechanism. With MCP alone, memory is something your agent calls, not something that happens in the background. OpenClaw and Hermes can have both: see Beyond MCP: first-class memory.

Before you start

You need three things.

1. A reachable address for each server. Both endpoints sit at the path /api/mcp. What comes before that path is not a fixed value for either server — it depends on how you reach your appliance, and for Companion Memory also on how it was installed.

Every example in this section writes those two origins as <hub-url> and <memory-url>. Work out yours before you start:

Companion Hub — on the LAN or over a VPN it is port 5002. By public URL or tunnel there is no port at all.
Companion Memory — no fixed port on any route. 8642 is the port inside its container, not on your appliance.

Both are shown in the Hub dashboard, and each server’s page above also covers its tools, scopes, and quirks.

If you have seen HUB_MCP_URL injected into an app’s environment, that value is the complete internal Docker address, path included — http://ci-os-hub:5002/api/mcp. It resolves only inside the appliance’s container network. From your own machine, use the LAN address of the appliance or a tunnel origin.

2. Two API keys. They come from different places and are not interchangeable. See Get Your API Keys.

3. Hub’s MCP server running. It is on by default — it loads unless someone has explicitly set MCP_ENABLED=false. Confirm with cihub mcp config on the appliance host if you are unsure.

On Windows, install where the agent actually runs. Both OpenClaw and Hermes can run natively or inside WSL2, and the two have separate homes: a ~ typed in PowerShell is C:\Users\<you>, while a ~ inside the distro is the Linux home, and neither agent treats a missing directory as an error — it simply loads nothing. Native Hermes is the one to watch, because its home is %LOCALAPPDATA%\hermes rather than ~/.hermes. Each page below gives the Windows form of its commands alongside the bash one.

Pick your client

OpenClaw Hermes Claude Code, Cursor, and others

Or let your agent do it

If the client you are connecting is itself a capable agent, it can read the setup and wire itself up. The ci-connect skill is this whole section written for a model rather than a person — every endpoint, both first-class-memory routes, and the traps below.


https://docs.ci.computer/connect/SKILL.md

Two ways to use it, and the difference matters:

	How	When
Once	Paste that URL and ask the agent to connect itself	A one-off setup, or a client you are trying out
Installed	Save it to a skills directory the agent scans	You want it available whenever the task comes up again — including on a machine you set up later

Installing takes one file and one config line, and a single directory serves both OpenClaw and Hermes: see installing the skill .

Installing a skill does not run anything. Both agents load skills as guidance consulted when a task matches, so this is about the instructions being available later, not about a setup step happening now.

It cannot mint your API keys — nothing can, that path needs a browser or the appliance host — so have both ready before you start, exactly as above.

Know before you wire it up

Three things account for nearly every failed setup. Each has a full explanation on the Troubleshooting page, but they are worth knowing in advance.

The path is `/api/mcp`, not `/mcp`

The two servers report this mistake differently: Companion Memory answers 405 Method Not Allowed and Companion Hub answers 404 Not Found. Neither reads like “wrong path”, which is why this is worth knowing before you start. See 405 or 404.

Both servers take `Authorization: Bearer`

Hub accepts only that header. Memory accepts either Authorization: Bearer or x-api-key. Use Authorization: Bearer for both and you have one pattern to remember instead of two.

Every client names the transport differently

All three speak the same protocol. They disagree only on how you declare it, and one of them fails silently when you get it wrong.

Client	Field	Value
OpenClaw	`transport`	`streamable-http`
Hermes	omit the field entirely	—
Claude Code	`type`	`http`

Security

The key you paste into a third-party client can do everything that key is permitted to do, and it lives in that client’s config file until you revoke it.

Mint a key per client, so you can revoke one without disturbing the others.
Choose the lowest capability that works. A key for memory recall does not need permission to uninstall your apps. See Choosing a capability.
Prefer an environment-variable reference over pasting the key into a config file, wherever your client supports it.
Browser-based MCP clients will not work against Companion Memory. It sends no CORS headers, so a browser cannot call it at all. Hub is looser — it reflects any localhost origin with credentials allowed — but that is an exposure to keep in mind rather than an integration to build on. Treat both as server-side and CLI endpoints.

If you lift a config file out of the packaged OpenClaw app, drop its gateway.controlUi block first — allowInsecureAuth, dangerouslyDisableDeviceAuth and allowedOrigins are set there because the packaged app runs behind the appliance’s own authenticated proxy. In a standalone install there is no such proxy, so they remove authentication rather than relaxing it.

Beyond MCP: first-class memory

MCP alone gives your agent memory it can query, not memory that accumulates on its own. An agent connected only over MCP has to call a memory tool during a conversation for anything to be stored — telling it so in your system prompt is usually enough.

Passive capture, and bootstrap context injected at the start of a session, come from a memory provider registered in the agent’s native memory slot. That is a different mechanism from MCP, and for OpenClaw and Hermes it is published separately:

Agent	Provider	Set up
OpenClaw	`@companionintelligence/openclaw-memory`	First-class memory
Hermes	`@companionintelligence/hermes-memory`	First-class memory

Each page documents two routes: the official commands for that ecosystem, and a cihub connect command if you are working on the Hub host (for Hermes it finishes by handing off to the official wizard). The two are independent of the MCP setup above — you can do either, both, or neither.

One thing to know before minting the key: the provider talks REST, not MCP, so its key needs the Memory scope at capability Read & write — a key minted for the MCP sections alone cannot store anything, and the failure is silent. Each page spells this out; so does Get Your API Keys.

Other MCP clients have no equivalent mechanism to plug into, so for Claude Code, Cursor, and others memory stays something the agent calls.