›Wait — MCP? API key? Workspace? Here are the 5 terms first

- AI agent: an AI that does not just chat with you but actually carries out the work you ask of it. Examples are programs like Claude Code, Claude Desktop, and Codex. Throughout this guide, whenever you see "agent," just think "your AI."
- API: a channel through which programs exchange information. Instead of a person clicking buttons on a screen, your AI uses this channel to send Rootr requests like "show me this document" or "add a line here."
- API key: the "key" that opens that channel, and also your ID badge. It is a long string that starts withrootr_, and only an AI holding this key can reach your material. That is why, like a password, you must never show it to anyone.
- MCP: a rule (a convention) that lets an AI use outside tools in a standard way. In plain terms, it is a "universal adapter between your AI and Rootr." Connect over MCP and your AI treats Rootr like a folder on its own computer.
- Workspace: the space where your documents and folders live. Think of it as one "work room" for a company. Each workspace has its own id.

Once your AI connects to Rootr over MCP or the API, holding your key (API key), it can work with documents, questions, and data directly.

Paste a URL — connect with nothing installed

For non-developersEasiest~2 minClaude · ChatGPT

This is the non-developer route. No install, no terminal, no config files. Claude and ChatGPT both connect with this one address:
- 1 In your AI's settings, open Connectors → Add custom connector. Paste the address above into the address field.
- 2 A Rootr screen opens in your browser: log in and press Allow. This is where you pick the workspace to connect and a permission level (read-only / read + write).
- 3 Rootr tools appear in your AI — that means it worked. Try asking: "What documents are in my workspace?"

Settings → Connectors → Add custom connector, then paste the address. It is the same on web and in the desktop app, and it works on the free plan.

Connecting automatically creates an "MCP remote connector" key in Settings → Integrations. Disconnect = revoke that key (access stops immediately).

One-click MCP key — connect the AI on your computer

Rootr builds the settings you need for the connection automatically. All you do is copy them and paste them into your AI.
- 1 Open Settings from the left-hand menu, then click the Integrations tab.
- 2 Under "AI agent integration (MCP)", press the Create MCP key… button.
- 3 Give the key a name, choose how much access to allow (permissions), and press Create. Pick a name you will recognize later — for example, "Claude on my laptop".
- 4 A configuration with your key (API key) already filled in appears in the code box below.
- 5 Press the copy button that matches the AI you use, and paste it in as the tabs below explain.

The one-click MCP integration screen in Settings → Integrations. It shows a copy-ready configuration with the issued key filled in, plus per-target copy buttons.

This is Claude in the terminal. Paste the one-line command you copied straight into a terminal window and run it — the connection is done.

Important: the API key (your key) is shown on screen only once, at creation time. Once you close the window you cannot see it again, so copy it somewhere safe. If you ever lose it or it leaks, just delete (revoke) that key from the key list in Settings → Integrations and create a new one.

Registering MCP in a config file yourself

If you are comfortable with development and want to manage config files directly, add it as shown below. This is a setting that tells your AI to "run a small program (rootr-cli) that connects to Rootr." Put the key you made above intoROOTR_API_KEY, and your workspace id intoROOTR_WORKSPACE.

-H "x-api-key: rootr_xxxxxxxxxxxxxxxx" \

-H "content-type: application/json" \

-d '{"workspaceId":"ws_123","path":"/notes/log.md","content":"Deploy finished"}'

Ask your knowledge a question and get an answer with evidence

-H "x-api-key: rootr_xxxxxxxxxxxxxxxx" \

-H "content-type: application/json" \

-d '{"question":"why have payment failures increased?"}'

It is fine if you do not know exactly what each command means. The point is that you "carry your key in the header and send a request to the address." You can find the complete list of every request you can make in the technical document (OpenAPI) linked from ⑩ Reference.

The two kinds of keys (API keys) and their permissions

There are two kinds of keys, and they differ in how wide a range they can open. Each key also carries a set of permissions (scopes) that decide "how much it is allowed to do." Allowing only as much as you need is the safe choice.

- Examples of permissions (scopes): docs:read (read documents) · docs:write (edit documents) · graph:read (browse knowledge) · ask (ask questions) · webhooks:manage (set up notifications). If you only want it to read, turn on docs:read alone.
- The principle: for most connections, a workspace key is enough. An account key has broad permissions, so use it only when you truly need it.
- To move between work rooms: a workspace key does not open anything outside its own room. For the AI to switch with rootr_use_workspace, use an account key, or issue one key per room and register them withrootr config --add-key <key>.

Keys are shown only once. Managing and revoking (deleting) them is all done in one place — the key list in Settings → Integrations.

Once connected, you just tell your AI in plain language ("summarize this document and add it below"). For results that are safer and more accurate, have it follow the points below.

- For adding content, have it use "append" first, and for partial changes, "find and replace" (edit). The approach of rewriting the whole document can accidentally erase existing content, so use it only when it is truly needed.
- When building a workspace from a structure up, have the AI plan first, ask a few questions, and only then create it (so it does not build blindly).
- If you have set the AI to receive change notifications (webhooks) again, have it ignore "changes the AI itself made." Otherwise you get an endless loop where it reacts to the very notifications it created.

Once connected, your AI can use the tools below. This is a table summarized by category; a detailed description of each tool is in ⑩ Reference. For now, just get a sense of "wow, I can have it do this many different things."

›Open the full table by group (11 groups)

Your AI fetches the exact, current list when it connects. The table above is a summary to give you a feel for what you can ask for.

If you have several workspaces, you can move between them mid-conversation without reconfiguring anything — just tell the AI "switch to the sales workspace" (by name or by id).

- With an account key (PAT): you can switch to any workspace you belong to.
- With a separate key per workspace: register each key once (rootr config --add-key <key> --label "Sales") and the right key is selected — and remembered — whenever you switch.
- A remote connector (the paste-a-URL option) stays bound to the single workspace you approved, by design. Issue another connector for another workspace.

Only reads, searches, and questions count against a limit. Writing documents and uploading files never do (they are bounded by storage instead).

- At 80% used, your AI tells you how many queries are left today — so you are never cut off mid-task without warning.
- When the quota runs out, your AI reports it and points you at the upgrade page. It refills at midnight.

From sign-up to your first document, and building a whole workspace with AI — it takes just five minutes.

If Rootr is new to you, just follow this order. No development knowledge is needed.

- You can sign up with an email and password, or start in one click with a Google account.
- The first time you log in, you see a prompt: "Create your first workspace." A workspace is your own space that holds documents and folders.

On the left of the screen is a tree (a list that unfolds like branches). Here you create folders to organize things and create documents inside them. Think of it just like the folders and files on your computer.

A newly created workspace and the document tree (list of folders and documents) on the left.

2.3 Building it all at once with "Create with AI"

You do not have to build everything piece by piece from a blank screen. Write in one sentence "what you want to do" (for example, "make me a space to prepare a new product launch"), and after asking you a few questions, the AI automatically builds a ready-to-use structure complete with folders, documents, and tables.

The "Create with AI" window. Write what you want to do as a sentence and it generates a workspace structure automatically.

When you save a document, its contents are automatically organized into a "knowledge graph" in the background (details in chapter ⑥). Then go straight to chapter ① and connect your AI — that is where the real power of Rootr begins.

Many people can write comfortably at the same time, and just by saving, the content automatically becomes searchable, queryable knowledge.

Rootr documents are made of pieces called "blocks." A heading, a paragraph, a list, a table, an image — each is a block. You can drop them in wherever you like and reorder them, which makes writing far more flexible.

- Real-time co-editing: even when several people open the same document and edit it at once, everyone's changes show up instantly. You can also see who is looking at what.
- Version history (an automatic save log): every time you edit a document, its previous state is saved automatically. Even if you delete something by mistake, you can roll back to an earlier version (the clock icon in the top right).
- Special blocks: you can add highlight boxes (callouts), tags (labels), and mermaid diagrams — pictures like flowcharts drawn with code. Even when the AI writes a document, it draws these diagrams automatically.
- Content added from outside shows in real time too: when an AI or a program adds text to a document via the API, it appears right away on the screen of whoever has that document open.

The block editor screen. Alongside a heading and a list, a flowchart (mermaid diagram) is drawn.

Below is the version history screen. The moments you edited the document remain as a list, so you can check or roll back to the content at any of those points anytime.