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, which is faster for work across many notes.
Install the kribble CLI as described in The kribble CLI, then run kribble login. Choose Read and write notes if agents should change notes.
kribble mcp installIt 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.
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 Desktop |
|
Codex (the CLI, the IDE extension and the app) |
|
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.
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).
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:
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:
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.
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.
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 <!-- kribble:start --> and <!-- kribble:end --> markers and replaces only that section when you run it again. kribble update refreshes a skill installed in your home directory.
The MCP server gives agents these tools. Agents that use the CLI have the same abilities through its commands.
Tool | What it does |
|---|---|
| List the spaces, and the folders and notes in a space |
| Full-text search, with the search box's operators ( |
| A note as markdown, with its id, path, version and children |
| A note's history, an old version, and the diff between two versions |
| Notes changed since a time: through this token (default), through any access token, or by anyone |
| Replace exact text in a note; everything else stays as it is |
| Replace a note's content; fails if the note changed since the version the agent read |
| Create, move or rename, change the name, description, icon or order, and delete notes and folders |
| Read and take part in comment threads |
| The published sites with their build status, and where sites can be published |
| 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.
search_notes takes the same query as the search box in the app (Search 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.
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.
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.
Agents take part in comment threads:
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.
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:
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.
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).
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 |
|---|---|
| Using the MCP server at |
| Changing notes and comments, pushing docs with |
| The import API ( |
| Rebuilding a space's site with |
The Scopes list offers these combinations:
Choice | Scopes | Use it for |
|---|---|---|
Publish + Import |
| CI that calls the HTTP endpoints directly |
Publish only |
| Publishing and rebuilding sites from CI: |
Import only |
| Importing or pushing docs from CI |
Read only (MCP) |
| Agents that only read |
Read + Write (MCP agents) |
| Agents that edit, and the CLI in CI ( |
All scopes |
| 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.
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:
kribble mcp install --docs https://docs.example.comThis 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.