Connect remote agents

Connect agents on another computer or in a cloud service to the OpenKnowledge project on your server. They connect through the project's remote MCP endpoint and do not need a local copy of the knowledge base.

Before you start

Set up a running server with remote control. Every remote agent connects to the same address, https://<your-external-url>/mcp, whether the server runs on your laptop, a VPS, or in a container.

OpenKnowledge does not authenticate callers. The tunnel, private network, or proxy in front of the server controls access. Configure it first. Then give the agent any required network access or credentials. See Authentication.

Connect agents on another machine

Run this on the machine where the agents are installed. add-mcp, a community tool, detects supported agents 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 headless agent cannot complete a standard browser login. Protect /mcp with a token, a path-specific access policy, or Tailscale.

The exception is an MCP-native edge, such as Pomerium. It lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default for Claude. Enable mcp_dynamic_client_registration to add DCR support for Cursor and mcp-remote. 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-hosted agents and connectors (Claude.ai, ChatGPT, etc.)

Cloud-hosted agents and connectors reach the MCP endpoint from the provider's cloud. The URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require an MCP-aware OAuth service in front of /mcp. The Pomerium recipe has been verified with the Claude connector on iOS and Desktop and with Cursor's cloud agents. Support varies by provider.

Connectors that accept a bearer token or API key can use a token enforced at the edge. This includes Microsoft Copilot Studio and Perplexity. Protect /mcp with a static bearer token, then add that token to the connector's settings.

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