Concepts

$ concepts · 6 min read

capsol is a small server you run yourself. Its whole job is to hold shared context that AI agents can read and write — so that every agent on a project works from the same page instead of its own private notes.

If you remember one thing: a capsule is a shared box of context, and it lives at one stable URL that many agents connect to at once.

What is a capsule?

A capsule is a container of context that you and your AI agents share. It has:

One stable URL. Paste it into any AI client and that agent joins the capsule.
Shared state. Many agents can connect to the same capsule, and they all see the same content. When one agent writes something, the others see it too.

Think of it like a shared document folder — except instead of people opening it, AI agents read and write to it as they work.

Why shared context matters

Most AI tools forget. Each chat, each editor, each laptop starts fresh, and useful knowledge — how your project is laid out, the decisions you’ve made, the conventions to follow — gets re-explained over and over.

A capsule fixes that by being a single shared place that follows the work:

Switch from Claude to Cursor? The context is still there.
Open a second laptop, or onboard a teammate? Same capsule, same knowledge.
Run an automated agent in CI? It reads the same notes a human’s agent wrote.

Nothing is wired per-machine. The dashboard hands you a URL, and that’s the only thing an agent needs.

What’s inside a capsule: schemes

Content inside a capsule is organized by schemes — labelled drawers for different kinds of content. Each entry has an address like docs://architecture or notes://q2-planning.

Six schemes are built in, and capsule owners can add their own from the dashboard.

Scheme	What it holds
`docs://`	reference docs, architecture, API refs
`guidance://`	patterns and team conventions
`notes://`	notes and findings
`config://`	config references
`api-data://`	JSON schemas and data models
`skills://`	reusable prompts

skills:// is a little special: those entries also show up to agents as ready-to-run prompts, not just readable content.

What agents can do: MCP tools

Agents talk to a capsule over MCP (Model Context Protocol — the standard way AI clients connect to outside tools). Through it, an agent gets a set of capsol_ tools. Which tools an agent has depends on what it’s been allowed to do (its scopes).

Tool	What it does
`capsol_read`	list, search, and read entries
`capsol_write`	create, append to, or edit entries
`capsol_signal`	leave short coordination notes for other agents
`capsol_capsules`	browse the directory of capsules (universal endpoint)
`capsol_manage`	operator actions (restricted)
`capsol_memory`	the agent’s own private memory (never shared)

The everyday two are capsol_read and capsol_write. capsol_signal is for teams of agents that need to hand off work or say “I’ve got this part.” capsol_memory is private scratch space for a single agent and is never visible to others.

How connecting works

Connecting an agent is mostly paste-and-approve:

Copy the capsule’s MCP URL — it looks like http://your-host/mcp/<capsule-id>.
Paste it into an MCP client — Claude Code, Claude Desktop, Cursor, Zed, VS Code Copilot, Codex, Windsurf, or ChatGPT (Pro and above).
The person signs in. The client handles the technical sign-in automatically.
A human approves the request in the dashboard. Nothing connects until someone says yes.

A key safety point: credentials are never in the URL. The URL is only an address. The access token rides separately, in the background, so sharing a URL doesn’t hand out access.

You decide who — and which agents — can reach a capsule. There are two ways:

Grant access directly. In the capsule’s Access tab, add a person or agent and choose what they can do.
Share the URL. Send someone the capsule URL and let them connect their own client. They still go through the approval step before they’re in.

Access is described by roles and scopes. Roles are the simple shorthand:

Role	Can do
reader	read content
appender	read and add to existing entries
writer	read, add, and edit content
owner	full control, including managing access

Under the hood, each grant carries fine-grained scopes (capsule:read, capsule:append, capsule:write, capsule:manage, signal:send). Access can also be narrowed to specific content — for example, limited to certain schemes, to URLs that start with a given prefix, or to exact entries. That lets you give an agent exactly the slice it needs and nothing more.

Under the hood

For readers who want the technical shape:

The sign-in flow is standard OAuth. When a client connects, it auto-discovers the server, registers itself (dynamic client registration), and uses PKCE for a secure exchange. The token then travels in the Authorization header — that’s why it’s never in the URL.
Storage is plain files. There’s no database. A capsule’s contents are files on disk, which makes them easy to back up, inspect, and move.
It’s self-hosted and open. You run the server; the data stays with you. capsol is licensed Apache-2.0.
One universal endpoint can list capsules across the registry via capsol_capsules, while each capsule still has its own dedicated URL.

Where next

Quickstart — get a capsule running and an agent connected.
Dashboard — create capsules and manage access.
Connect your agents — use capsules in real agent workflows.
Access & sharing — roles, scopes, and approvals in depth.
Architecture — how capsol is built.