Agents & MCP · Documentation

Create an API token

Open a vault and go to Agents & MCP. In the Connect your AI tools step, click Generate token: the setup commands below fill in with your new token, ready to copy. The token is shown once, so copy it right away. As soon as your AI tool reads the vault for the first time, the tab confirms the connection.

Right after your first build, the reveal screen offers the same in one click: Add to Cursor and Add to VS Code open the editor's install prompt with the server already configured, and the Claude Code command is ready to copy.

A folder share link (Team) opened in a browser shows a guest page: who shared which folder, until when, and the same one-click setup for the guest's own agent. A guest's agent starts at the shared folder: its map lists that folder and the subfolders the link may open. A guest's agent never counts as yours: it does not trigger your "agent connected" moment or pause your browser extension. Share links stop working if their creator or an owner of the vault is suspended (see Teams & organizations).

The sample vault cannot be connected to agents: it holds demo data about someone else. Connect your agents to your own vault.

You can also create tokens with a chosen role (Owner, Admin or Member), access and expiry in the API tokens card. Every call is filtered by the folders that role is allowed to read. Access is one of:

Full access: reads and writes like the role allows.
Review-only: reads, and every write (facts and lessons) waits in Quarantine for your approval.
Read-only: only the read tools are offered.

One-click keys (the Connect your AI tools step and the reveal screen) state their role and expiry, which you can change (90 days by default; Member in team vaults). A vault can have up to 50 active tokens: revoke one you no longer use to make room. The browser extension needs a full-access owner or admin key (see below).

The gateway is a Streamable HTTP endpoint at https://app.contextos.dev/api/mcp, authenticated with Authorization: Bearer ctxos_…. Self-hosted nodes use https://your-domain/api/mcp.

ChatGPT connectors cannot send headers, so they connect with a ChatGPT link (/api/mcp/k/…): click Create ChatGPT link in the ChatGPT setup. The link carries its own limited token, review-only (read-only on plans without agent writes), and expires after 90 days. Full-access tokens are never accepted in a link, because links end up in logs, browser history and screenshots. Keep the link private and revoke it in the API tokens card like any token.

The Agents & MCP tab generates ready-to-paste snippets for Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT and any other MCP client, plus a Test connection button. The test does not count as agent activity: it never pauses your browser extension or adds to your agent calls.

The tools

Tool	What it does
`get_master_map`	Returns `AGENTS.md` and `SOUL.md`, filtered to the folders your role can see
`read_folder_readme`	Returns a folder's index: purpose, routing rule and files with their TL;DRs
`read_context_file`	Reads one Markdown file (long files in 40,000-character parts: `offset` and `limit`) and counts as "tokens served"
`search`	Finds the files that best match a question (ranked locally, no AI cost), with the matching line
`fetch`	Opens one search result by its path or file id, with its TL;DR and tags
`propose_context_update`	Saves new facts; sovereign files, low-confidence facts and team members' writes go to Quarantine
`remember`	Saves one fact without choosing a file: the vault routes it like `propose_context_update`
`record_agent_feedback`	Appends corrections and mistakes to `Lessons_And_Mistakes.md` so future sessions learn from them

search and fetch follow the shape ChatGPT connectors and deep-research agents expect.

On the Free plan the gateway is read-only: the read tools (get_master_map, read_folder_readme, read_context_file, search, fetch) work, while writing facts needs Pro, an active Import Pack month, or Team.

In a team vault, writes from a member's token (facts and lessons) always wait in Quarantine until an owner or admin approves them; owner and admin tokens write directly, except to sovereign files. Agents only ever see the folders their token's role can open: maps, folder indexes and the Changelog are rebuilt for that role, so they never mention folders it cannot read. Paths with .. segments or hidden control and text-direction characters are refused, and earlier versions of every changed file are kept (see Privacy & storage).

Agents never write the files Context OS maintains: routing maps, folder README.md indexes, .cursorrules, .windsurfrules and Changelog.md are refused, and so are hidden and .git folders. A fact aimed at another name the vault reserves (such as Historical_Archive.md, or Lessons_And_Mistakes.md inside a folder) is saved with a _Notes suffix instead (Historical_Archive_Notes.md). Secrets in anything an agent sends (facts, reasons, section and agent names) are replaced with placeholders such as [REDACTED_SECRET_1] before anything is stored.

Each channel drops its own duplicates before any AI call, so they never cost tokens: MCP ignores the same facts proposed again for the same file and section, and the extension ignores chat messages it has already captured. The two channels do not deduplicate each other: if an agent summarizes a chat over MCP and the extension also captures that chat, it can be distilled twice.

Each token and each share link has its own rate limit (240 and 120 calls a minute), so a busy guest never locks you out. A share link can have at most 25 proposals waiting in Quarantine (a token 100), and every Quarantine card shows which token or share link made the proposal.

Browser extension

The extension prefills new ChatGPT, Claude, Gemini and Grok chats with your vault's map and captures new conversations back into the vault.

It caches AGENTS.md and SOUL.md locally, so injection is instant and free.
Context is added once per conversation, only into the chat's own message box (never into posts, direct messages or other editors on the page), also when you switch chats without reloading.
It skips injection only on the site whose own MCP connector is active (for example ChatGPT with a ChatGPT link), so context is never added twice. Agents outside the browser, such as Cursor, Claude Code or VS Code, never pause it, and capturing never depends on MCP.
Captured chats are scrubbed for secrets in the browser and sent only after a quiet period of 5–10 minutes. Only new or edited messages are sent, never the whole conversation again, and chats captured within 10 minutes of each other are distilled together.
Temporary and incognito chats are never injected or captured.
Capturing chats needs a full-access owner or admin key: with a Member key the extension only prefills chats with your context, and captures are refused. Owners and admins create one with Create a key for the extension on the extension card in the Agents tab, which also shows the Server URL to paste; members ask an owner or admin for a key.
Captured chats wait in a local outbox until the server confirms them: offline, server errors or a used-up token pool only delay them, and nothing is lost. The popup shows what is waiting. Changing the server URL or the key drops the chats still waiting, so a chat never reaches another vault or server.
A passphrase-locked vault is not prefilled until you unlock it, and captured chats wait until then.
The server URL is the app's address, not the MCP endpoint (a pasted /api/mcp address is corrected, and an address where no Context OS server answers is reported). It must use https:// (plain http:// only for localhost). The popup's Page check shows whether the extension found the chat's message box on the current page.

Install it (early access)

The extension's Chrome Web Store listing is in review. Until it is live, install the packaged build in developer mode. It works in Chrome, Edge and Brave:

In your vault, open Agents and click Download for Chrome, Edge & Brave, then unzip the file. The card shows the version and the SHA-256 checksum of the package.
Open chrome://extensions (or edge://extensions, brave://extensions) and turn on Developer mode.
Click Load unpacked and select the unzipped folder.
Open the extension's options and paste the Server URL shown on the extension card (on Context OS cloud, keep the default https://app.contextos.dev) and the key from Create a key for the extension (or one an owner or admin gave you).

Developer-mode extensions do not update automatically: download the new package from the Agents tab when a new version is announced. Once the store listing is live, the Agents tab links to it instead.