Connect Your Agent

One server, every client: knowlery mcp speaks MCP over stdio, so any MCP-capable agent can host your knowledge base. This page has a section per client. Everything after connection is the same everywhere — see Talk to Your Knowledge Base.

The fastest path: install the plugin

The Knowlery agent plugin bundles the MCP server (auto-provisioned via npx) plus all fifteen skills. Install it with two commands:

• Claude Code: /plugin marketplace add JayJiangCT/knowlery → /plugin install knowlery
• Codex: codex plugin marketplace add JayJiangCT/knowlery → codex plugin add knowlery@knowlery
• Cursor: install from a checkout's plugin/ dir or the release zip (until the marketplace listing lands)

Details in Install as a plugin. The manual MCP config below remains fully supported — use it when you want the server without the skills, or on clients without a plugin system.

Before you start

Two equivalent ways to provide the server; every section below works with either:

// A. Zero-install (recommended): npx fetches the package on first run
{ "command": "npx", "args": ["-y", "knowlery@^1", "mcp"] }

// B. Installed CLI: one line, PATH handled with your consent
//    curl -fsSL https://jayjiangct.github.io/knowlery/install.sh | sh
{ "command": "knowlery", "args": ["mcp"] }

The installer puts the CLI in an isolated prefix (~/.knowlery/cli, no sudo, no global npm), links it into ~/.local/bin, and — only if that directory isn't on your PATH — shows the exact line and asks before touching any shell config. Re-running it upgrades in place. (npm i -g knowlery works too, with the usual global-prefix PATH caveats.)

One caveat worth knowing for GUI clients (Claude Desktop, IDEs): they often don't inherit your shell's PATH, so npx/knowlery may not resolve if node was installed via nvm/homebrew. The bulletproof form is absolute paths: "command": "/absolute/path/to/node", "args": ["/absolute/path/to/knowlery-cli.mjs", "mcp"] — or at least the absolute path to npx (which npx).

At a glance

Client	Config location	Notes
Claude Code	claude mcp add	full support
Claude Desktop	claude_desktop_config.json	shell-less: register_kb is how existing KBs join
Codex CLI	Plugins or ~/.codex/config.toml	/plugins opens the plugin browser; config is shared with the desktop app
Codex Desktop	Plugins or shared config.toml	plugins supported; start a new task after installation
Codex IDE extension	~/.codex/config.toml	MCP config supported; plugins unavailable
OpenCode	~/.config/opencode/opencode.json	first-class Knowlery platform — see the config-ownership note
Cursor	~/.cursor/mcp.json or deeplink	project-level .cursor/mcp.json also supported
Antigravity Desktop / CLI / IDE	~/.gemini/config/mcp_config.json	one config serves all three

Claude Code

claude mcp add knowlery -- npx -y knowlery@^1 mcp

Restart the session; the tools appear automatically. Claude Code also reads vault-installed skills when you open a Knowlery workspace folder.

Claude Desktop

Settings → Developer → Edit Config, then add at the top level of claude_desktop_config.json (not inside preferences):

{
  "mcpServers": {
    "knowlery": {
      "command": "npx",
      "args": ["-y", "knowlery@^1", "mcp"]
    }
  }
}

Quit fully (Cmd+Q) and relaunch — the config is read at startup. Knowlery appears under Connectors. Claude Desktop has no shell, which is exactly what the MCP surface is for: register_kb brings existing KBs in from the conversation, and the nine tools cover the daily loop end to end.

Note: the "Managed MCP servers" settings page is for org-pushed remote servers (it requires a URL) — local stdio servers go in the JSON config above.

Codex CLI

For the complete plugin, run:

codex plugin marketplace add JayJiangCT/knowlery
codex plugin add knowlery@knowlery

Start a new Codex session after installation. Run /plugins in an interactive CLI session to inspect or enable the plugin. To install only the MCP server without the bundled skills, add this block to ~/.codex/config.toml instead:

[mcp_servers.knowlery]
command = "npx"
args = ["-y", "knowlery@^1", "mcp"]

Restart codex after changing the config. Since Codex has a shell, the knowlery CLI works alongside the MCP tools — the knowlery-cli skill teaches the command surface. Opened inside a Knowlery vault, Codex also loads the vault-root AGENTS.md — KNOWLEDGE.md, Knowlery's operating rules, and the rule files copied in — the same sources Claude Code gets through .claude/CLAUDE.md.

Codex Desktop

The marketplace installation above is shared with Codex Desktop. Relaunch the app, open Plugins → Installed, confirm that Knowlery is enabled, and start a new task. Type @ in the composer to select Knowlery or one of its bundled skills explicitly.

The app also shares ~/.codex/config.toml with the CLI, so the MCP-only block above works in both.

Codex IDE extension

The IDE extension does not support plugins. Use the MCP-only ~/.codex/config.toml block above, then restart the extension and start a new session.

OpenCode

OpenCode's config shape differs from the Claude family — the top-level key is mcp (not mcpServers), each entry declares "type": "local", and command is a single array carrying the binary and its arguments together (there is no separate args field):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "knowlery": {
      "type": "local",
      "command": ["npx", "-y", "knowlery@^1", "mcp"],
      "enabled": true
    }
  }
}

Add this to the global config at ~/.config/opencode/opencode.json (or run the interactive opencode mcp add). Verify with opencode mcp list.

The vault's instructions live in AGENTS.md

OpenCode is a first-class Knowlery platform: knowlery init --platform opencode writes rules under .agents/rules/ and a vault-root AGENTS.md that copies in KNOWLEDGE.md, Knowlery's operating rules, and those rules — the same sources Claude Code @-imports through .claude/CLAUDE.md. OpenCode loads AGENTS.md at session start (its opencode.json instructions array is no longer resolved in V2, so Knowlery stopped writing a vault-level opencode.json; knowlery sync retires an old one). The global config above is where the MCP block belongs — it serves every project at once.

OpenCode agents have a shell, so the knowlery CLI works alongside the MCP tools; the vault's AGENTS.md, .agents/rules/, and skills (installed by init/sync) already teach the retrieval conduct.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "knowlery": {
      "command": "npx",
      "args": ["-y", "knowlery@^1", "mcp"]
    }
  }
}

Reload the window (Cmd+Shift+P → "Reload Window"); check Settings → MCP for the server and its tools. Cursor agents have a shell, so the CLI form works too.

Antigravity 2.0 (Desktop, CLI, and IDE)

The Antigravity suite shares one MCP configuration across all three surfaces. Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "knowlery": {
      "command": "npx",
      "args": ["-y", "knowlery@^1", "mcp"]
    }
  }
}

• Desktop / IDE: restart; the tools attach to agent sessions.
• CLI (agy): run /mcp to confirm the server and inspect its tools.
• Shared skills (loadable across the suite) live under ~/.gemini/skills/ — the Knowlery plugin will target this layout when it ships.

Remote (any client, another machine)

All of the above run the server locally. To reach KBs hosted elsewhere, run knowlery mcp serve on the host behind a tunnel and point the client at the URL with a bearer token — see Remote access.

Verify the connection

In any connected client, ask:

List my knowledge bases.

You should get the registry listing (or "No knowledge bases registered" on a fresh machine — then say "set up a knowledge base for me" and go from there). If the server doesn't appear at all: check JSON/TOML syntax, use absolute paths (the GUI PATH caveat above), and confirm Node.js ≥ 20 is installed.