Overview

capsol is a self-hosted registry of context, skills, prompts, and resources that any MCP-speaking AI agent — Claude, Cursor, Codex, your own Mastra agent — can read and write through a single URL.

Pick your path

The docs are split by what you’re here to do:

Use capsol with your agents. capsol is already running somewhere and you want to connect your AI client to a capsule and put it to work. Start with Connect a client, then Work with your agents.
Run capsol for your team. You want to install, deploy, and manage it for others. Start with the Quickstart (install), then Deploy and Access & sharing.

Either way, Concepts explains the mental model in plain language.

Why a registry, not a local config

Most “memory for agents” tools live on your machine as a JSON config file, a vector store, or a folder the agent sees through the filesystem. That model breaks the moment you switch editors, open a second laptop, onboard a teammate, or run a CI agent.

capsol inverts it. You run one small HTTP server. You paste one URL into any MCP client. Every agent that opens that URL sees the same capsule — the same docs, the same skills, the same prompts, the same resources — with the same audit log and the same trust boundary. The registry is the integration point. There is no claude_desktop_config.json to hand-edit. There is no .capsol/ directory to git add.

What a capsule holds

A capsule is a container. Every capsule exposes configured URI schemes from day zero. The built-in palette is:

docs:// — reference docs, architecture, API refs. Markdown, versioned.
guidance:// — coding patterns and team conventions.
notes:// — investigation notes and findings.
config:// — config references (env-var layout, feature flags, deploy targets).
api-data:// — API schemas and data models, stored as JSON.
skills:// — reusable prompts. Writing to skills:// also registers the entry as an MCP prompt (the only scheme that feeds prompts/list); the other five are resource-only.

You don’t pick a kind up-front. You create the capsule, then add entries under whichever schemes you need. Capsule owners can add custom schemes such as runbooks:// directly from the dashboard; operators can also set registry-level schemes with CAPSOL_SCHEMES.

Mental model

  any MCP client ──────►  https://host/mcp/<capsule-id>  ──────►  capsule
  Claude Code                    (one URL)                     ├─ docs://
  Cursor                                                       ├─ guidance://
  Codex                                                        ├─ notes://
  your Mastra agent                                            ├─ config://
                                                               ├─ api-data://
                                                               └─ skills://  (also MCP prompts)

One URL. One capsule. Many agents. Every read returns a trust preamble and a provenance footer so agents verify before acting.

How to use it

Install. docker run -p 4000:8080 ghcr.io/arcadeai-labs/capsol-v2:latest (or run from source — see the Quickstart).
Admin credentials. First-run prints an admin key. Save it in a password manager now — it is never shown again.
Open the dashboard. http://localhost:4000. Sign in with the key.
Create a capsule. Click New capsule. Add a few context or skill entries, or leave it empty — agents can write into it.
Create the right connection. The dashboard hands you a stable URL (http://localhost:4000/mcp/<capsule-id>). OAuth-capable clients use discovery/DCR; autonomous agents can request enrollment and wait for human approval.
Paste into any client. Claude Code, Cursor, Claude Desktop, Codex, Zed, Windsurf, or any framework that speaks MCP. Never put credentials in the URL.

That is the whole install. No per-machine setup.

What clients work

Every host that speaks MCP over Streamable HTTP, which at time of writing means Claude Code, Claude Desktop, Cursor, Zed, VS Code Copilot, Codex CLI, Windsurf, ChatGPT (Pro+), and claude.ai (Pro+). See MCP clients for the paste-in config per host.

For agents you build yourself, capsol is a plain MCP server over Streamable HTTP at /mcp/<capsule-id>. LangChain, Mastra, Vercel AI SDK, OpenAI Agents SDK, Pydantic AI, and any MCP-capable framework connect with a URL. See custom agents.

At-a-glance

Aspect	Value
URI schemes	docs · guidance · notes · config · api-data · skills · custom schemes
Transport	Streamable HTTP over MCP
Auth	Operator login · OAuth MCP connections · approved agent enrollment
Clients supported	Claude Code, Claude Desktop, Cursor, Zed, VS Code, Codex, Windsurf, ChatGPT, claude.ai
Auditability	Append-only event log per capsule
Storage	Plain files under `$CAPSOL_DATA_DIR` — no database
License	Apache-2.0

When NOT to use capsol

You want a free-text chat-memory tool. capsol is structured. Every entry has a URI, a risk class, and a provenance footer. If you want blind “just remember this,” use something else.
You want embeddings. capsol deliberately has no vector store. Build one on top if you need semantic search.
You need multi-tenant SaaS billing. capsol is self-host. Billing is your problem.
Your agent does not speak MCP. We do not plan to add a REST-only integration path. MCP is the contract.

Where next

Quickstart — registry running, first MCP URL in under two minutes.
Concepts — what a capsule holds, the five MCP tools, URI schemes.
Dashboard — the day-to-day surface.
API reference — every HTTP endpoint, curl-copyable.