# AI agents > Connect Claude Code, Claude Desktop, Codex and other AI tools to Kribble, review what they change, and manage their access tokens AI agents can search, read and edit your notes, discuss them in comments and publish sites, with your permissions. Every change they save is a version you can review as a diff, marked with the access token they used. There are two ways in, and most setups want both: - **MCP**, for AI apps: Claude Code, Claude Desktop, Codex and any other tool that speaks the Model Context Protocol get Kribble's tools. - **The kribble skill**, for agents that run shell commands: it teaches them the [kribble CLI](../using-kribble/the-kribble-cli.md), which is faster for work across many notes. ## Connect Claude Code, Claude Desktop and Codex :::steps ::step Install the CLI and sign in --- Install the kribble CLI as described in [The kribble CLI](../using-kribble/the-kribble-cli.md), then run `kribble login`. Choose **Read and write notes** if agents should change notes. :: ::step Connect the apps --- ```bash kribble mcp install ``` It finds the apps on this computer and sets up each one. To set up only one, name it: `claude-code`, `claude-desktop`, `claude` (both Claude apps) or `codex`. Naming `claude-code`, `claude-desktop` or `codex` sets that app up even if the CLI can't find it. :: ::step Restart the apps --- Restart Claude Code, quit and reopen Claude Desktop, and restart Codex, so they load the new server. :: ::: What it sets up: | App | Where | | --- | --- | | Claude Code (the CLI and the desktop app's Code tab) | A user-scope MCP server, added with `claude mcp add --scope user`, or in `~/.claude.json` when the `claude` command isn't found | | Claude Desktop | `claude_desktop_config.json` in Claude's settings folder | | Codex (the CLI, the IDE extension and the app) | `~/.codex/config.toml`, edited so your own settings and comments stay | Each app starts `kribble mcp serve` when it needs Kribble. It uses the CLI's login, so no access token is copied into the apps' settings. It follows the active profile: after `kribble profile use NAME` or a new `kribble login`, the apps' next call goes to that profile, without setting them up again. To tie the apps to one profile instead, run `kribble mcp install --profile NAME`. If the CLI isn't signed in when an app starts, the app gets a single `kribble_connect` tool that says what is wrong. Run `kribble login` in a terminal and the agent can call it again; there's no need to restart the app. ```bash kribble mcp status # which apps are set up, and the profile they use kribble mcp uninstall # remove Kribble from the apps (name one to remove it from that one) ``` `--name NAME` changes the server's name in the apps (`kribble` by default). ### Other MCP clients Any tool that supports remote MCP servers over HTTP can connect to the server directly. The address is your server with `/mcp`, and the client sends an access token in the `Authorization` header: ```text URL: https://kribble.example.com/mcp Header: Authorization: Bearer kb_… ``` The token needs the `read` scope, and `write` for changes (see Access tokens and scopes below). For Claude Code, for example: ```bash claude mcp add --transport http kribble https://kribble.example.com/mcp \ --header "Authorization: Bearer kb_…" ``` A tool that starts local MCP servers instead can run `kribble mcp serve`, which speaks MCP over standard input and output with the CLI's login. ## The kribble skill Agents that can run commands work well with the CLI itself: for a change across many notes, an agent can `kribble pull` a folder, edit the files with its own tools, and `kribble push` them back. The skill tells the agent how: note paths, the markdown format, safe edits, working copies, comments, and how to show you what it changed. ```bash kribble skill --install claude # a Claude Code skill in ~/.claude/skills/kribble kribble skill --install claude --project # only for this project, in ./.claude/skills/kribble kribble skill --install agents # a section in ./AGENTS.md, for Codex and others kribble skill # print the guide, for any other agent ``` `--install agents` adds a section between `` and `` markers and replaces only that section when you run it again. `kribble update` refreshes a skill installed in your home directory. ## What agents can do The MCP server gives agents these tools. Agents that use the CLI have the same abilities through its commands. | Tool | What it does | | --- | --- | | `list_spaces`, `list_notes` | List the spaces, and the folders and notes in a space | | `search_notes` | Full-text search, with the search box's operators (`in:`, `by:`, `updated:` and the others). Returns each note's path and the headings that matched | | `read_note` | A note as markdown, with its id, path, version and children | | `list_versions`, `read_version`, `diff_note` | A note's history, an old version, and the diff between two versions | | `list_changes` | Notes changed since a time: through this token (default), through any access token, or by anyone | | `edit_note` | Replace exact text in a note; everything else stays as it is | | `write_note` | Replace a note's content; fails if the note changed since the version the agent read | | `create_note`, `move_note`, `update_note`, `delete_note` | Create, move or rename, change the name, description, icon or order, and delete notes and folders | | `list_comments`, `add_comment`, `reply_comment`, `resolve_comment` | Read and take part in comment threads | | `list_sites`, `list_deploy_targets` | The published sites with their build status, and where sites can be published | | `deploy_site`, `redeploy_site` | Publish a space, folder or note as a site, or build a published site again | An agent can only reach what you can reach, and only the spaces its token allows. Tools that change something need the token's `write` scope; with a read-only login, agents can search and read but not change anything. Publishing needs admin rights in the space, and the server tells agents to ask you before publishing anything new. See [Publishing sites](../using-kribble/publishing-sites.md). `search_notes` takes the same query as the search box in the app ([Search](../using-kribble/search.md) lists the operators) and a `limit` (20 notes by default, at most 100). Each result names the sections that matched, with the block each match is in. When an `in:` or `by:` matches no space, folder or person, the tool returns an error saying which, so the agent can correct it instead of guessing from an empty list. Dates in `updated:` count in UTC. An agent working in a repository, or in a folder pulled with `kribble pull`, can also run `kribble search --local [--dir DIR] QUERY`. It searches the markdown files on disk with the same syntax, needs no server or sign-in, and prints the file and line of each match. See [The kribble CLI](../using-kribble/the-kribble-cli.md). Notes are read and written as Kribble markdown. Edits through `edit_note` keep what markdown can't express, such as column widths and drawings, in every block they don't touch, which is why agents are told to prefer it to `write_note`. ## Review what agents changed Every save by an agent is a new version of the note, attributed to you and the access token it used: - Under a note's title, **Saved … by** shows the token for the latest version, for example "kribble CLI · my-laptop for you". - **History** in the top bar (on a phone, **⋯** › **Version history**) lists the versions; each one saved through a token says **via** and the token's name. Open a version to see its **Changes** as a diff, or its **Preview**, and **Restore this version** to undo the agent's change. - Each edit returns a diff to the agent, and agents are told to show it to you. - From the terminal, `kribble changes --since 2h --diff` lists the notes changed through this computer's token, with their diffs. `--by agents` includes every access token; `--by anyone` includes people's edits too. `kribble diff NOTE` shows one note's latest change. Give each agent or integration its own token if you want to tell their changes apart. ## Comments with agents Agents take part in [comment threads](../using-kribble/comments-and-reviews.md): - **Addressing comments**: ask the agent to work through a note's open comments. It reads them, changes the note, replies to each thread saying what it changed, and resolves the ones it has dealt with. It leaves a thread open with a reply when it needs your decision. - **Reviewing**: ask the agent to review a note, and it comments on quoted passages instead of rewriting the text. `@Name` in its comment notifies that person. For docs pushed from a repository, which are read-only in Kribble, an agent working in the repository reads the comments with `kribble comments`, fixes the markdown files, pushes them and replies to the threads. ## Access tokens and scopes Agents, CI jobs and other tools act through access tokens. `kribble login` creates one for you. To create one by hand, for CI or for an MCP client: :::steps ::step Open Access Tokens --- Open the organisation's settings (in the organisation switcher at the bottom of the sidebar, hover the organisation and click its gear icon) and choose **Access Tokens**. **CLI & agents** links to the tokens of your personal organisation. :: ::step Create the token --- Click **Create token**, give it a **Name** (shown next to every change made with it), and choose the **Scopes**, the **Space access** (**All spaces**, or **Specific spaces** and tick them) and the **Expiry** (never, 30 days, 90 days or 1 year). :: ::step Copy it --- Click **Create** and copy the token. It is shown only once. :: ::: A token acts as the person who created it, with their permissions; its scopes and spaces can only narrow what that person can do. The scopes: | Scope | Allows | | --- | --- | | `read` | Using the MCP server at `/mcp` at all, and so the CLI: reading, searching, history, comments | | `write` | Changing notes and comments, pushing docs with `kribble push`, and publishing and rebuilding sites through MCP or the CLI | | `import` | The import API (`POST /api/v1/spaces/{id}/import`) and the push API (`POST /api/v1/spaces/{id}/push`), for CI without the CLI | | `publish` | Rebuilding a space's site with `POST /api/v1/spaces/{id}/publish`; through MCP, publishing and rebuilding sites | The **Scopes** list offers these combinations: | Choice | Scopes | Use it for | | --- | --- | --- | | **Publish + Import** | `publish,import` | CI that calls the HTTP endpoints directly | | **Publish only** | `publish` | Publishing and rebuilding sites from CI: `kribble deploy`, `redeploy`, `sites` and `targets`, or the publish endpoint | | **Import only** | `import` | Importing or pushing docs from CI | | **Read only (MCP)** | `read` | Agents that only read | | **Read + Write (MCP agents)** | `read,write` | Agents that edit, and the CLI in CI (`kribble push` and the note commands) | | **All scopes** | `read,write,publish,import` | Everything | The CLI works through the MCP server, so a token for the CLI needs `read`, and `write` for `kribble push` and `kribble deploy`. A token created by `kribble login` with **All my organizations** works in every organisation you belong to, including ones you join later, with your permissions in each. It is listed under your personal organisation. Tokens created in an organisation's settings work only in that organisation. The list shows each token's name, the start of the token, its scopes, its spaces, its expiry and when it was last used. You see your own tokens; people who manage the organisation's tokens see everyone's. **Revoke** stops a token at once. ## Published docs for agents Sites published from Kribble carry a markdown copy of every page, `llms.txt`, `llms-full.txt` and `kribble-docs.json`, so that anyone's agents can use them. Readers connect their AI apps to a site with: ```bash kribble mcp install --docs https://docs.example.com ``` This needs no account on your server, and gives agents `search_docs`, `read_page` and `list_pages` for that site. For a private site, the reader must be a member of the space and have signed the CLI in to the same server. Details are in [Publishing sites](../using-kribble/publishing-sites.md).