Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect GBrain to Claude Desktop
This page covers connecting Claude Desktop to a remote brain. For a brain
on the same machine as Claude Desktop, a local stdio entry in
claude_desktop_config.json with "command": "gbrain", "args": ["serve"]
works too — but only against a full local install, never a thin-client one.
For remote setup, first select native OAuth/PKCE or a private machine handoff according to the connection settings available in your installed Claude product. To open the owner dashboard or manage its clients, use MCP administration; the harness's OAuth scope does not grant that authority.
Important: Claude Desktop does NOT connect to remote MCP servers via
claude_desktop_config.json. That file only works for local stdio servers.
Remote HTTP servers must be added through the GUI.
Say to your agent: "connect claude desktop to my brain" — on the brain
host, the remote-mcp skill publishes with gbrain mcp expose when needed,
then MCP administration supplies the URL and setup for your chosen
authentication method. You finish in the Claude Desktop GUI below.
Shortcut: one link
If your brain has a public HTTPS address, one link opens Claude's Add custom connector form with the address filled in. Check it, click Add, then sign in. The connector lands in your Claude account, so Claude Desktop and claude.ai both get it.
- Hosted GBrain:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=GBrain&connectorUrl=https%3A%2F%2Fgbrain.io%2Fmcp - Your own brain:
gbrain mcp expose --funnelprints the link for your URL (theClaudeline underNext).
A tailnet-only brain (plain gbrain mcp expose) gets no Claude link, because
claude.ai connects from Anthropic's servers. If the form opens empty (today
the filled-in values are lost after a sign-in redirect and on iPhone Safari),
use the manual steps below.
1. Publish the brain (host side)
Claude Desktop runs on your own device, so the tailnet-only default is enough — nothing is exposed to the public internet:
gbrain mcp expose # prints https://your-machine.your-tailnet.ts.net/mcp
If the brain already has an HTTPS endpoint, use it instead. Register a native
OAuth client or provision a private machine handoff through the running
server's owner API, according to the
installed client's settings. The expose-managed owner credential is at
~/.gbrain/serve/admin-token; it is never a client credential.
Say to your agent: "put my brain on tailscale" — "connect claude desktop to my brain".
Legacy bearer settings on PGLite:
gbrain auth create "claude-desktop" --scopes read,writeopens the database, which fails withlive_servewhile the expose-managed service holds it. Mint the token before the service runs (ahead ofgbrain mcp expose, or while the service is stopped briefly), or provision through the running server instead —gbrain mcp grant … --admin-token-file ~/.gbrain/serve/admin-tokenor the/admindashboard. Postgres brains mint fine while the server runs.
The device running Claude Desktop must be on the same tailnet (Tailscale
installed and signed in). Full walkthrough and troubleshooting:
remote MCP guide. Using ngrok instead? Its URL is
https://YOUR-DOMAIN.ngrok.app/mcp (ngrok-tunnel recipe).
2. Add the integration
- Open Claude Desktop
- Go to Settings > Integrations
- Click Add Integration (or Add Connector)
- Enter the MCP server URL:
Use your MagicDNS name as printed byhttps://your-machine.your-tailnet.ts.net/mcpgbrain mcp expose, or the existing HTTPS endpoint (ngrok alternative:https://YOUR-DOMAIN.ngrok.app/mcp). - Choose the authentication method that the settings support. For native OAuth, use the owner-issued client metadata and the native connection procedure. For an existing bearer connection, enter its private scoped token. Never enter the server's owner bootstrap credential as the MCP credential.
- Save
Verify
Start a new conversation and try:
Search my brain for [any topic]
Observe the actual GBrain tool call and result. A saved configuration alone does not establish that this Claude Desktop session loaded or connected the server.
Common Mistakes
Using claude_desktop_config.json for remote servers — this silently fails with no error message. The JSON config only works for local stdio MCP servers. Remote HTTP servers must be added via Settings > Integrations in the GUI.
Using the wrong URL — make sure the URL ends with /mcp (not /health
or just the base domain).
Name does not resolve on this device — the device is not on the tailnet,
or MagicDNS is off for it. Sign in to Tailscale on the device and enable "Use
Tailscale DNS settings"; gbrain mcp expose --status on the host confirms
the server side. See the troubleshooting table.