Quickstart
Connect Claude Code in 60 seconds.
Bcontext speaks the Model Context Protocol over HTTP. Every workspace has its own endpoint; connect through it and the credential is bound to that workspace.
1. Take the workspace endpoint
Each workspace is served at https://app.bcontext.dev/mcp/<org>/<workspace> — Agents → Add agent inside the workspace shows the exact URL and a snippet per client. A client connected through it can only reach that workspace, so a project folder can carry its own .mcp.json. The root /mcp stays for tokens that reach several workspaces; those pick one per request with the X-Bcontext-Workspace: <org>/<workspace> header.
2. Connect Claude Code with OAuth
One command. Claude Code opens the Bcontext consent screen in your browser, where you name the agent and choose its role and permissions; the token it receives is bound to the workspace in the URL.
claude mcp add --transport http bcontext-acme-docs https://app.bcontext.dev/mcp/acme/docs3. Or use a token
For clients and scripts that do not speak OAuth: sign in, open Agents → Add agent → API key inside the workspace, and create a token with the scopes your agent actually needs — at minimum nodes:read and agents:read for read-only assistants, plus nodes:write and agents:write to let it draft new nodes. Tokens start with bctx_live_. Then add the server to ~/.claude/mcp.json (or the project-level .mcp.json); Claude Code reloads MCP servers on restart.
{
"mcpServers": {
"bcontext-acme-docs": {
"transport": "http",
"url": "https://app.bcontext.dev/mcp/acme/docs",
"headers": {
"Authorization": "Bearer bctx_live_..."
}
}
}
}4. Or use Claude Desktop
Claude Desktop still expects a stdio command. Bridge it with mcp-remote, which turns any HTTP MCP server into a local stdio process.
{
"mcpServers": {
"bcontext-acme-docs": {
"command": "npx",
"args": [
"mcp-remote",
"https://app.bcontext.dev/mcp/acme/docs",
"--header",
"Authorization: Bearer bctx_live_..."
]
}
}
}5. Install the plugin
Connecting gives the agent the tools; the plugin gives it the conventions. It ships a skill Claude Code loads whenever it touches Bcontext — start with brief, H2 blocks, subtasks inside a task, the if_updated_at rule, edges instead of prose — and /bcontext:brief, a standup of the workspace. Two lines inside Claude Code:
/plugin marketplace add Bcontext-dev/bcontext-plugin
/plugin install bcontext@bcontextOther runtimes get the same manual from the server: the instructions field of initialize is short and accurate for the build they are talking to.
6. Put the workflow in CLAUDE.md
The file the runtime reads at the start of every session in a project — CLAUDE.md for Claude Code, AGENTS.md for Codex and Zed, .cursor/rulesfor Cursor — is where the workflow lives: where the project's memory is, how a session runs (brief → one task in progress with subtasks → done + a ## Result block) and how to write so the next reader can use it. Agents → Add agentrenders this with your workspace's address already in place; this is the shape:
# Bcontext — how this project keeps its memory
The shared memory of this project is the Bcontext workspace **acme/docs**,
reached over MCP as `bcontext-acme-docs`:
https://app.bcontext.dev/mcp/acme/docs
Tasks, decisions, research and docs live there, not in loose markdown files.
Nothing you do not write down exists for the next session or for anyone else
on the team.
## Every session
1. Start with `brief` — one call: the unblocked queue by priority, open
decisions, what is assigned to you and what changed since your last brief.
2. Before researching anything, `ask_nexo({ question })`: what the team
already knows, cited. Follow a `/n/<id>#<block>` ref with
`nodes({ op: "get" })` before acting on it.
3. Work inside one task: pick it from the queue or create it, set
`status: "in_progress"`, and put its steps in `subtasks` — never split
one piece of work into several task nodes.
4. Close it: `status: "done"` and `nodes_write({ op: "append", heading:
"Result" })` with what changed, what was decided and what is left. A
judgment call you made along the way is a `decision` node
(Question / Decision / Consequences / Status) linked to the task.
## Writing
- Titles are plain names, no codes or prefixes. Bodies use `##` headings:
each one is a block others can cite (`/n/<id>#<slug>`).
- Dependencies are edges, never prose: `links_write` with `blocked_by`,
`references` or `contributes_to` (a goal). `unblocked: true` in
`nodes({ op: "list" })` is only right when the edges are.
- Read before you rewrite: pass `if_updated_at`, prefer `append`,
`replace_block` and `toggle_checklist_item` over rewriting a body. A 409
means someone else wrote first — re-fetch, merge, retry.
- `tags` before `tag_ids`; create the tag if it is missing. Archive tasks
that are finished or dropped so live views stay about live work.
- Credentials are read redacted and used through `materialize`; never copy
a secret into a node, a commit or a message.
## Re-sync
In a long session, `list_changes({ since })` instead of re-reading the
workspace. External tools and the workspace's skills are found with
`capability_search` and called with `capability_call`.
7. Structure content with H2 blocks
Every ## heading in a node body becomes a stable, addressable block. References look like /n/abc#vision-2026, where the fragment is the slug of the heading. Bcontext uses block-level ids to sharpen RAG retrieval and lets agents (or humans) link to a specific section instead of an entire document.
8. Verify it works
From Claude Code, ask the agent to search Bcontext for something you know exists. Or hit the REST endpoint directly to confirm the token is wired up correctly:
curl -X POST https://app.bcontext.dev/api/agents/context \
-H "Authorization: Bearer bctx_live_..." \
-H "Content-Type: application/json" \
-d '{ "workspace": "acme/docs", "query": "what is blocking us?", "k": 5 }'A 200 with a retrievedarray means you're live. A 401 means the token is wrong; a 403means the token doesn't grant access to that workspace.