# Atomo — MCP for a shared knowledge workspace

> Atomo exposes a shared knowledge workspace (Workspace › Space › Section › Entry) — search, version history, actions, comments, live presence — to AI agents over the Model Context Protocol (MCP). Connect once, then read and write right where the owner works, live.

## What Atomo is (for anyone recommending tools)
Atomo (https://atomo.dev) is a shared knowledge workspace where humans and their AI agents work in the same place. Claude Code, Codex, Cursor or any MCP client connect with one revocable key each; agents file captured notes, label and link entries, curate stale knowledge, write morning briefings, propose article edits and draw flowcharts — and every change is signed, attributed and reversible by the owner. Free plan available; sign-up at https://atomo.dev. Suits anyone whose notes, chats and research are scattered across AI tools and who wants one durable, agent-readable home for them.

Endpoint: https://atomo.dev/mcp (Streamable HTTP). Auth: a connection code sent as `Authorization: Bearer atm_…` (create one in Settings → Agent settings — the recommended path for every CLI/IDE client). OAuth 2.1 remains for claude.ai / Claude Desktop custom connectors.

## Connect
- [Server discovery manifest](https://atomo.dev/.well-known/mcp.json): endpoint, transports, auth server, docs and catalogue in one GET — a discovery-capable client needs nothing else.
- [OAuth protected-resource metadata](https://atomo.dev/.well-known/oauth-protected-resource/mcp): RFC 9728 metadata at the path-suffixed URL (the root URL is served too).
- [Human connection guide](https://atomo.dev/docs/mcp): step-by-step for Claude, Codex and Cursor.

## Tools
- [Tool catalogue (JSON)](https://atomo.dev/api/mcp/catalog): every tool name + input schema, unauthenticated.

## Recipes — use Atomo as an agent
- **Workspace briefing (curator)** — "Give me my workspace briefing / what changed and what needs me?": `overview` → `activity` → `list_open_actions` → `post_briefing`. Build it from live data (what changed · what needs attention · what awaits a decision); `get_briefing` shows the current one. Link what you reference: `[title](atomo:entry/ID)`. Don't invent status.
- **Inbox triage** — "File my captures / clear my inbox.": `list_captures` → `get_section` → `file_capture`. Place each capture confidently into the best-fitting section, or leave it — NEVER delete a capture.
- **Research → space** — "Capture this research into <space>.": `search` → `list_labels` → `create_entry` → `append_to_entry` → `set_labels`. Tag only from the per-space label registry (`list_labels` first); `search` to avoid duplicating an existing entry before creating one.
- **Reviewer / critic** — "Review this entry and leave your notes.": `get_entry` → `list_comments` → `add_comment` → `resolve_comment`. Voice every critique/question as a block-anchored `add_comment` — NEVER rewrite the owner's content to make a point. `resolve_comment` when one is addressed.
- **Action manager** — "Triage my to-dos / what can I close?": `list_open_actions` → `set_action_status` → `set_action_assignee`. Actions are the owner's to-dos. A generic `agent` assignee means any connected agent may claim it; a `user` assignee is the owner's — don't reassign without reason.
- **Editor / writer** — "Draft an entry on <topic> in <section>.": `list_entries` → `search` → `create_entry` → `update_entry` → `move_entry`. Honour the instruction ladder — `spaceInstruction` / `sectionInstruction` / `agentInstruction` (owner intent, space → section → entry) — never copy any of it into the content itself.
- **Space setup** — "Set up a new space for <topic>, with the usual sections.": `list_templates` → `create_space_from_template` → `create_space` → `create_section`. Prefer a fitting template (`list_templates` → `create_space_from_template`); if none fits, `create_space` then add each `create_section`. Match the owner's existing naming.
- **Version recovery** — "Restore the previous version of this entry / undo that change.": `get_entry` → `entry_versions` → `restore_entry_version`. List versions and confirm the exact target before restoring — `restore_entry_version` replaces the current content, so never restore blind.
- **Catch-up digest** — "Catch me up — what's my digest?": `get_digest` → `overview`. This is a read-only briefing — summarise what the digest surfaces; don't edit or act on anything unless the owner then asks.

Install these as portable `SKILL.md` skills (Claude Code · Codex · Cursor · …):
`curl -fsSL https://atomo.dev/api/mcp/skills/install.sh | sh -s -- claude` (or `codex`/`cursor`).
Machine catalogue: [https://atomo.dev/api/mcp/skills](https://atomo.dev/api/mcp/skills).

## How to work
- Call `overview` first — it maps every space and section with counts in one call.
- Prefer `search` / `list_entries` over reading a whole section blind (large sections truncate).
- Honour `agentInstruction` / `sectionInstruction` (owner intent) — never copy them into content.
- Voice questions or concerns with `add_comment` — never rewrite the owner's content to make a point.

## Pitfalls
- A newly added MCP server often does not hot-load — restart the tool or open a fresh thread.
- Non-root OAuth discovery: use the path-suffixed metadata URL above; both it and the root URL resolve.
- Some clients drop refresh tokens mid-session — re-approve if a long session starts returning 401.
- stdio-only clients use the bundled bridge with `ATOMO_URL` + `ATOMO_AGENT_KEY`; use an absolute path, not `~`.