# Wire agent editors

> Connect Claude Code, Cursor, and Codex via MCP registration, bundled skills, `ok repair-skills`, and verification prompts that exercise the `exec` tool.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `packages/cli/src/commands/editors.ts`
- `packages/cli/src/commands/repair-mcp-configs.ts`
- `packages/cli/src/commands/install-skill.ts`
- `packages/cli/src/commands/repair-skills.ts`
- `docs/content/integrations/claude-code.mdx`
- `docs/content/integrations/cursor.mdx`
- `docs/content/integrations/codex.mdx`

---

---
title: "Wire agent editors"
description: "Connect Claude Code, Cursor, and Codex via MCP registration, bundled skills, `ok repair-skills`, and verification prompts that exercise the `exec` tool."
---

Open Knowledge registers the `open-knowledge` MCP server and installs bundled agent skills into Claude Code, Cursor, and Codex. `ok init` performs the first-time wiring; every `ok start` runs reclaim sweeps that refresh stale MCP entries and skill bundles. The project-local `open-knowledge` skill teaches agents to route markdown reads through the MCP `exec` tool instead of native file tools.

## Supported editors

| Editor | MCP server name | User config path | Project config path | Project skill path |
| --- | --- | --- | --- | --- |
| Claude Code | `open-knowledge` | `~/.claude.json` (`mcpServers`) | `.mcp.json` | `.claude/skills/open-knowledge/SKILL.md` |
| Claude Desktop | `open-knowledge` | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) | — | — |
| Cursor | `open-knowledge` | `~/.cursor/mcp.json` (`mcpServers`) | `.cursor/mcp.json` | `.cursor/skills/open-knowledge/SKILL.md` |
| Codex | `open-knowledge` | `~/.codex/config.toml` (`mcp_servers`; override home with `CODEX_HOME`) | `.codex/config.toml` | `.agents/skills/open-knowledge/SKILL.md` |

`ok init` detects installed editors by probing each editor's config directory. Editors that are not installed are skipped with `skipped-missing` rather than creating config files for absent tools.

<Note>
Claude Desktop's **Code** tab uses the same MCP wiring as Claude Code. Claude **Chat** and **Cowork** use a separate upload flow via `ok install-skill` — they do not read project MCP config.
</Note>

## MCP entry format

Published installs write a managed shell-chain entry tagged with the `# ok-mcp-v1` sentinel. The chain resolves the `ok mcp` subprocess in order:

1. `~/Applications/Open Knowledge.app/Contents/Resources/cli/bin/ok.sh mcp` (user-installed Desktop app)
2. `/Applications/Open Knowledge.app/Contents/Resources/cli/bin/ok.sh mcp` (system Desktop app)
3. `npx -y @inkeep/open-knowledge@latest mcp`
4. `npx` from common Node version-manager paths (`nvm`, `fnm`, `asdf`, Homebrew, Volta, and others)

If none resolve, the chain exits 127 with an install hint.

<ParamField body="command" type="string">
Always `/bin/sh` for published installs.
</ParamField>

<ParamField body="args" type="string[]">
`["-l", "-c", "<chain script>"]` where the script body includes `# ok-mcp-v1`.
</ParamField>

Contributor local development uses `--dev-mcp` on `ok init`, which registers `node packages/cli/dist/cli.mjs mcp` with `MCP_DEBUG=1` and `OK_LOG_FILE=/tmp/ok-mcp.log` instead of the published chain.

## Two skill bundles

Open Knowledge ships two bundled skills from `packages/server/assets/skills/`:

| Bundle | Skill name | Installed where | Purpose |
| --- | --- | --- | --- |
| **Project** | `open-knowledge` | Project tree under each editor's `skills/` directory | Runtime contract: STOP rules for native file tools on in-scope `.md`/`.mdx`, MCP tool routing table, preview handshake, grounding rules |
| **Discovery** | `open-knowledge-discovery` | `~/.agents/skills/open-knowledge-discovery/` plus per-host copies when the host directory exists | Install and sharing guidance only — no runtime read/write rules |

`ok init` always writes project-local `open-knowledge` skills for Claude Code, Cursor, and Codex. It also runs `installUserSkill` to place the discovery skill in the user's global skill directories.

<Warning>
Agents editing markdown inside an initialized project must load the **project-local** `open-knowledge` skill, not the discovery skill. If only discovery is loaded, advise the user to re-run `ok init`.
</Warning>

## Wire editors

<Tabs items={['macOS Desktop app', 'CLI (`ok init`)']}>

<Tab>

On first project open, OK Desktop shows a consent dialog that detects installed MCP-capable editors and offers to register `open-knowledge`. Click **Add** to write user-level MCP entries for each detected editor.

To re-trigger the dialog after skipping or changing editors, delete `~/.ok/mcp-status.json` and relaunch the Desktop app.

</Tab>

<Tab>

From the project root:

```bash
ok init
```

Non-interactive environments default to writing MCP config at **both** user and project scopes. In a TTY, `ok init` prompts for scope:

- **User-level** — `~/.claude.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`
- **Project-level** — `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`

<ParamField body="--scope" type="user | project | both">
Override the interactive scope prompt.
</ParamField>

<ParamField body="--no-mcp" type="flag">
Scaffold `.ok/` without touching any editor MCP config.
</ParamField>

<ParamField body="--dev-mcp" type="flag">
Register a local dev MCP entry (`node` + `packages/cli/dist/cli.mjs`) instead of the published chain.
</ParamField>

<ParamField body="--shared" type="flag">
Commit OK config artifacts alongside content (default for fresh repos).
</ParamField>

<ParamField body="--local-only" type="flag">
Keep OK config out of git via `.git/info/exclude`.
</ParamField>

For Claude Code, `ok init` also scaffolds `.claude/launch.json` with an `open-knowledge-ui` configuration that starts the editor preview via the same resolution chain pattern (`# ok-ui-v1` sentinel).

</Tab>

</Tabs>

```mermaid
sequenceDiagram
  participant User
  participant CLI as ok init / ok start
  participant Config as Editor MCP config
  participant Skill as Bundled SKILL.md
  participant Agent as Claude / Cursor / Codex
  participant MCP as ok mcp (stdio)

  User->>CLI: ok init
  CLI->>Config: write open-knowledge entry (# ok-mcp-v1 chain)
  CLI->>Skill: copy project + discovery skills
  User->>Agent: open project, approve MCP server
  Agent->>MCP: spawn ok mcp subprocess
  MCP-->>Agent: tools/list (exec, search, write, …)
  Agent->>MCP: exec("ls -A …")
  MCP-->>Agent: enriched document listing
```

## Approve the MCP server

After wiring, each editor prompts you to approve the new `open-knowledge` MCP server on next project open.

| Editor | Approval behavior |
| --- | --- |
| Claude Code | May pre-approve via `--settings '{"enabledMcpjsonServers":["open-knowledge"]}'` when launched from Open with AI handoffs |
| Cursor | Shows an MCP approval prompt — approve `open-knowledge` before tools are visible |
| Codex | Restart Codex after wiring if tools do not appear |

Until approval completes, the agent cannot call Open Knowledge MCP tools.

## Automatic reclaim on `ok start`

Every `ok start` runs three reclaim sweeps before booting the collaboration server. Failures are logged and do not block server startup.

| Sweep | Function | What it fixes |
| --- | --- | --- |
| MCP config repair | `repairMcpConfigs` | Rewrites stale `open-knowledge` entries (legacy bare `npx`, direct bundle paths, symlinks) to the current `# ok-mcp-v1` chain |
| Launch JSON repair | `repairLaunchJson` | Updates `.claude/launch.json` `open-knowledge-ui` entry to the current `# ok-ui-v1` chain |
| Skill repair | `repairSkills` | Refreshes bundled `SKILL.md` files at project and user scopes |

<ParamField body="OK_RECLAIM_DISABLE" type="string">
Set to `1` to skip all three sweeps. Only the exact value `1` disables reclaim; other values (`0`, `true`, empty) do not.
</ParamField>

### MCP config repair outcomes

`repairMcpConfigs` scans user-level and project-level config for every editor in `ALL_EDITOR_IDS`. For each config file:

| Outcome | Meaning |
| --- | --- |
| `no-entry` | Config exists but has no `open-knowledge` server entry — left untouched |
| `canonical` | Entry already contains `# ok-mcp-v1` — no write |
| `repaired` | Stale entry rewritten to the managed chain |
| `write-failed` | Lock or I/O error during atomic write |

There is no standalone `ok repair-mcp-configs` command — MCP repair runs only as part of `ok start` (and Desktop launch reclaim).

## `ok repair-skills`

Force an explicit skill reclaim sweep outside of `ok start`:

```bash
ok repair-skills
```

**Project sweep** — for each editor host directory (`.claude`, `.cursor`, `.agents`):

| Outcome | Condition |
| --- | --- |
| `reclaimed` | Existing `SKILL.md` replaced with current project bundle |
| `created` | No skill file, but MCP config contains `# ok-mcp-v1` — skill created |
| `no-token` | No skill and no wired MCP entry — skipped |
| `failed` | Path safety or I/O error |

**User sweep** — refreshes `open-knowledge-discovery` at `~/.agents/skills/open-knowledge-discovery/` and per-host copies (`.claude/skills/`, `.cursor/skills/`) when the host directory exists. Skips when the recorded version in `~/.ok/skill-state.yml` already matches the bundled server package version.

<RequestExample>

```bash
ok repair-skills
```

</RequestExample>

<ResponseExample>

```text
Skill reclaim complete.
  Project: 2 reclaimed, 1 created, 0 no-token, 0 failed.
  User (0.19.0): 3 written, 0 skipped, 0 failed.
```

</ResponseExample>

Exit code is non-zero when the project sweep is skipped (bundle missing), user sweep fails (except `version-current`), or any individual write fails.

## Verify wiring with `exec`

Registration — not top-level tool-name visibility — is the test for whether Open Knowledge MCP is active. After approving the server, confirm the agent routes reads through MCP by asking:

<CopyPrompt>List the first 5 documents you come across in this project.</CopyPrompt>

A correctly wired agent calls the Open Knowledge `exec` tool (for example `exec("ls -A …")`) and returns document names with enriched metadata (frontmatter, backlink counts, recent activity). It should **not** use native `Read`, `Grep`, or `Glob` on in-scope markdown.

| Signal | Meaning |
| --- | --- |
| Agent lists project documents via `exec` | MCP + project skill wiring is working |
| Agent uses native file tools on `.md` files | Project skill not loaded, or MCP not approved — re-run `ok init`, restart editor |
| Agent reports MCP unavailable | `ok mcp` subprocess failed to start — check Node 24+, Desktop app, or `npx` resolution |
| `exec` works but writes fail | Collaboration server may be down — run `ok start` for server-routed writes |

<Info>
The `exec` tool is server-free for reads: it runs an allowlisted bash subset (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`) against the content directory and returns enriched metadata per referenced wiki file. One command or pipe per call — no `&&`, `;`, or redirects.
</Info>

If verification fails after approval, restart the editor so it reloads MCP config and skills.

## Claude Desktop Chat and Cowork

`ok init` wiring does not reach Claude Chat or Cowork. For those surfaces:

```bash
ok install-skill
```

This builds `~/Downloads/openknowledge.skill` and opens Claude Desktop for manual upload (**Customize → Skills → + → Create skill → Upload skill**). Use `--force` to bypass the install-state gate and rebuild unconditionally.

## Troubleshooting

<AccordionGroup>

<Accordion title="Editor does not see Open Knowledge tools">

1. Confirm MCP config contains an `open-knowledge` entry with `# ok-mcp-v1` in the command chain.
2. Approve the server in the editor's MCP settings.
3. Restart the editor.
4. Run `ok start` to trigger MCP and skill reclaim sweeps, or `ok repair-skills` for skills only.
5. Re-run `ok init` to rewrite config and project skills.

</Accordion>

<Accordion title="Stale MCP entry after upgrade">

Legacy entries (`npx @inkeep/open-knowledge mcp`, direct bundle paths, symlinks) are rewritten automatically on `ok start`. Check stderr for `mcp-config-migrate` JSON events with `surface: cli-repair`.

</Accordion>

<Accordion title="Project skill missing but MCP is wired">

`ok repair-skills` creates the project skill when MCP config contains `# ok-mcp-v1` even if `SKILL.md` is absent. Without either signal, the sweep reports `no-token` for that editor.

</Accordion>

<Accordion title="Disable automatic reclaim">

Set `OK_RECLAIM_DISABLE=1` before `ok start` or `ok repair-skills` to skip MCP, launch.json, and skill sweeps. Useful when debugging custom MCP entries.

</Accordion>

<Accordion title="Re-trigger Desktop consent dialog">

Delete `~/.ok/mcp-status.json` and relaunch OK Desktop.

</Accordion>

</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Initialize a project" href="/initialize-project">
Run `ok init` to scaffold `.ok/`, install skills, and register MCP for detected editors.
</Card>
<Card title="Quickstart" href="/quickstart">
End-to-end path from install through first agent-driven edit.
</Card>
<Card title="MCP tools reference" href="/mcp-tools-reference">
Full `exec`, `search`, `write`, and 14 other MCP tool contracts.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
`ok diagnose health`, repair stale configs, and recover from crash leftovers.
</Card>
</CardGroup>