Connecting other agents (archi connect)

Open WebUI is one client of an instance. Any agent that speaks MCP over streamable HTTP can use the same graph tools. The endpoint is http://127.0.0.1:<ports.mcp>/mcp; the bearer token is OKG_CHAT_MCP_TOKEN in the instance .env.

Who can read the graph

In 3.0, access is all or nothing. Every client of an instance uses the same token, and anyone who holds it can read the whole published graph. There is no per-user, per-group or per-record filtering, and no single sign-on for the MCP endpoint. A request with no token or a wrong one gets HTTP 401.

Clients connected with archi connect also get query, the raw SQL read tool. The Open WebUI preset leaves it out, but the server offers it to every client that holds the token. It runs as the read-only okg_mcp database role and refuses anything but SELECT and WITH. Give the token only to people who may read everything in the instance.

The ports listen on 127.0.0.1 only. To reach the instance from another machine, use an SSH tunnel.

Configure a client

archi connect claude-code [--instance DIR] [--print | --write [PATH]] [--show-token] [--embed-token]

--print (the default) shows the config. --write merges it into the client's config file (default path below). A config file that exists is never replaced: archi adds or updates its own entries (archi-<instance name> and the external servers) and keeps everything else. Running the same command again changes nothing. A file that archi cannot parse is left alone and the command stops.

The token is not printed unless you pass --show-token. Printed and written configs carry ${OKG_CHAT_MCP_TOKEN}, which Claude Code and OpenClaw expand from the environment, so export the variable (from the instance .env) in the shell that starts the client. A new file is mode 0600. --write --embed-token writes the literal token instead; archi refuses unless the file is outside any git repository or git ignores it (git check-ignore), and tightens an existing file to 0600. A symlinked config is written through to its target.

For Codex, archi sets only the keys it owns in [mcp_servers.<name>] (url, bearer_token_env_var, env_http_headers). Your own keys there (startup_timeout_sec, tool_timeout_sec, enabled, sub-tables) and the rest of the file are kept. The file is read with a TOML parser, and the result is checked to differ from the old file only in those tables; otherwise nothing is written.

Client Default file Format Checked how
claude-code ./.mcp.json mcpServers.<name> with type: "http", url, headers Matches what claude mcp add --transport http NAME URL --header "H: V" writes (run against the installed CLI).
codex ~/.codex/config.toml [mcp_servers.<name>] with url, bearer_token_env_var, env_http_headers Codex's MCP documentation. Codex speaks streamable HTTP itself; no stdio bridge such as mcp-remote is needed. Codex reads the token from the environment: export OKG_CHAT_MCP_TOKEN=.... Not run against a Codex binary.
openclaw ~/.openclaw/openclaw.json mcp.servers.<name> with url, transport: "streamable-http", headers OpenClaw's configuration documentation only; not run against a live OpenClaw. The file is JSON5: archi merges only strict JSON and otherwise tells you to merge by hand. Check with openclaw mcp show.
mcp ./archi-mcp.json mcpServers.<name> JSON The shape most MCP clients read; for any client not listed.
open-webui none none archi up already registered the server (okg chat sync); the command prints the URL the site uses (http://mcp:<port>/mcp), the site URL and where the token is.

External MCP servers

Declare them in the instance's archi.yaml:

mcp_servers:
  - name: notes                       # lowercase letters, digits, - _
    url: https://notes.example.org/mcp
    headers:
      Authorization: NOTES_AUTH       # header name -> NAME of an environment variable

The variable holds the whole header value (for example Bearer abc). The file is committed, so it never holds a secret; a value that is not a variable name, a URL with credentials or a query string, an unknown key, a duplicate name or the instance's own server name stops archi connect with the reason.

archi connect writes these entries next to the instance's own, as ${NOTES_AUTH} references (Codex: env_http_headers). Export the variable before starting the client. Open WebUI is not synced from this block; the command lists them to add under Settings > Admin > External Tools.

Checking a recipe without a model

python/tests/connect/recipe_check.py reads a written config, connects exactly as the client would (URL and headers as written; ${VAR} and Codex's variables come from the environment or --env-file DIR/.env; an unset variable is an error), calls search on the instance server and echo on any external server that has one, and prints a JSON result. Exit 0 means every call succeeded.

archi connect claude-code --write /tmp/probe/.mcp.json
python python/tests/connect/recipe_check.py --client claude-code \
    --config /tmp/probe/.mcp.json --env-file DIR/.env --query "CMSSW"

For Open WebUI, python/tests/connect/webui_check.py --instance DIR signs in as the site admin, reads the tool server the site registered, and runs an MCP client inside the webui container (podman|docker exec) that calls search at that registered URL over the compose network; it exits 0 only if the answer cites rows.

python/tests/connect/fixtures/echo_server.py is a small external server (one echo tool) for trying the mcp_servers: path.