Docs / Agents

Agents over MCP

Uberblick is built MCP first. The agent writes most of what is in a workspace: it searches, reads, edits block by block, keeps the data current and comments. The browser is where you review, adjust and settle what the agent should not decide. Register the server once with your agent's client and that is the whole setup.

Register the server

Run this in the project directory, with Claude Code or Codex installed:

Terminal

# Project scope, following ./.uberblick.json
$ ub mcp install claude

# Codex, or per-user instead of per-project
$ ub mcp install codex
$ ub mcp install claude --user

The command runs the client's own installer (claude mcp add, codex mcp add) and registers one server named uberblick that runs ub mcp serve. It never edits a config file itself. If an entry named uberblick already exists and is not ours, it is left alone and the snippet is printed instead. Restart the client, or reload its MCP servers, after installing.

For a client the command does not know, ub mcp install cursor --print prints the snippet and does nothing else.

Which workspace the agent sees

The server follows the nearest .uberblick.json above the directory the client started in, the same binding the terminal commands use. Agents never choose a workspace; they inherit the project's selection. Restart a running agent after you change the binding, because it keeps the workspace it started with.

A session can use several workspaces through separately named entries in the client's own config, each with its own UB_WORKSPACE_ID and UB_HUB_URL; see Configuration.

The tools an agent actually uses

There are 25 tools; most sessions use these eight. Each tool's own description is the authority, and get_help returns the product help an agent should read before it writes. The full list, with every parameter, is in the MCP reference.

Tool	When an agent reaches for it
`get_sidebar`	First thing in an unfamiliar workspace: the pinned documents and their groups say what matters here.
`search`	Find the pages a change touches before touching anything.
`get_doc`	Read a page block by block, with the block ids needed to edit it.
`find_decisions`	Before changing behaviour an issue covers: which decision records link that issue or pull request.
`edit_block`	Change the one block that is wrong. The rest of the page stays as it was.
`insert_block`	Add a paragraph, a table or a chart at a position, rather than rewriting the page.
`update_data`	Write records into a document; every chart and table that reads them refreshes.
`annotate`	Comment on a range, or reply to and resolve a thread, the same threads people see beside the text.

The rest: create_doc, list_docs, backlinks, list_tags, delete_block, link_range, set_metadata, set_status, get_data, export_markdown, pin_doc, unpin_doc, sidebar_group, archive_doc, restore_doc, sync_status, get_help.

What to tell your agent

The server does not decide how an agent should behave; your instructions do. Three rules that have held up for us:

Start from get_sidebar and search, not from memory. Cite pages by title and id.
Edit the block that is wrong with edit_block. Do not replace a page to change a sentence.
Before changing behaviour an issue touches, call find_decisions for that issue and read what comes back.