Connecting agents

Prerequisite: a running server with remote access set up. OpenKnowledge doesn't authenticate callers itself; the edge in front of it (a tunnel or proxy) decides who can reach the URL (see Authentication). To add someone else's machine, first get them through that edge (a tailnet invite, an allowlist entry, or the shared token), then send them here.

Every client below points at the same address, https://<your-external-url>/mcp, whether the server runs on your laptop, a VPS, or a container.

Connect every agent in one command

add-mcp, a community tool, detects which agents are installed on the machine and writes each one's MCP config for you (Claude Code, Cursor, Codex, VS Code, Windsurf, Goose, Zed, and more):

npx add-mcp https://<your-external-url>/mcp --name ok-remote

If your /mcp endpoint is behind a token at the edge (a bearer token or Basic Auth from your Authentication setup), pass it as a header so the agent connects with no browser step:

npx add-mcp https://<your-external-url>/mcp --name ok-remote \
  --header "Authorization: Bearer <your-token>"

For Basic Auth, the header is Authorization: Basic $(printf 'user:pass' | base64) instead.

A plain OAuth/SSO login can't be used this way: a headless agent can't complete a browser sign-in. Gate /mcp with a token, a path-branched policy, or Tailscale instead.

The exception is an MCP-native edge (such as Pomerium), which lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default (which Claude uses) and DCR when you enable mcp_dynamic_client_registration (which Cursor and mcp-remote use), so both work; the Pomerium recipe turns both on.

The per-client setups below use a plain /mcp URL. If yours is behind a token, add the same Authorization header shown above (details in Authentication).

Claude Code

claude mcp add --transport http ok-remote https://<your-external-url>/mcp

Cursor

{
  "mcpServers": {
    "ok-remote": { "url": "https://<your-external-url>/mcp" }
  }
}

Codex

Recent Codex versions take the URL directly:

[mcp_servers.ok-remote]
url = "https://<your-external-url>/mcp"

Claude Desktop

Claude Desktop only takes command-type servers, so it reaches the server through the mcp-remote bridge, a local process that forwards to your /mcp URL.

Its config file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. In Claude Desktop open Settings → Developer → Edit Config, which creates the file and reveals it. Then add:

{
  "mcpServers": {
    "ok-remote": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-external-url>/mcp"]
    }
  }
}

If your /mcp is behind a token, add it to the args array: "--header", "Authorization: Bearer <your-token>".

Agent harnesses (OpenClaw, Hermes, etc.)

Add the /mcp URL to your harness's MCP server config, the same way as above. Its agents can then read and write your knowledge base.

Cloud connectors (Claude.ai, ChatGPT, etc.)

Cloud-dialed clients connect from the vendor's cloud, so your URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require OAuth, which OpenKnowledge does not serve itself; an MCP-aware OAuth edge in front of /mcp supplies it. The Pomerium recipe is the path we've verified for the Claude connector (iOS and Desktop) and Cursor's cloud agents, though connector support otherwise varies by vendor. Connectors that accept a bearer token or API key instead (Microsoft Copilot Studio, Perplexity, etc.) can use a token you enforce at the edge: gate /mcp with a static bearer token (an ngrok traffic policy, a Cloudflare Access service token, or your auth proxy), then paste that same token into the connector's settings, the way an on-device agent presents its credential as a header.

Claude Desktop is not a cloud connector; it uses the mcp-remote bridge covered above.