# Bcontext

The context layer for the AI-first company. Typed knowledge graph + RAG + agent-writeable endpoints.

## Discovery

- https://app.bcontext.dev/.well-known/agents.json — capabilities, scopes, endpoints, MCP URL

## Authentication

All API and MCP calls require a workspace-scoped bearer token:

    Authorization: Bearer bctx_live_<43chars>

Tokens are issued from the Bcontext workspace settings → Tokens. Each token belongs to one workspace; scope checks gate per-operation.

## Examples

Search a workspace via RAG:

    curl -X POST 'https://app.bcontext.dev/api/agents/context' \
      -H 'Authorization: Bearer bctx_live_…' \
      -H 'Content-Type: application/json' \
      -d '{"workspace":"my-ws","query":"open auth decisions","k":6}'

Propose batched writes (idempotent):

    curl -X POST 'https://app.bcontext.dev/api/agents/write' \
      -H 'Authorization: Bearer bctx_live_…' \
      -H 'Idempotency-Key: agent-42-batch-7' \
      -H 'Content-Type: application/json' \
      -d '{"workspace":"my-ws","ops":[{"op":"create","node":{"title":"New ADR","kind":"adr","parent_id":null}}]}'

## CLI (preferred when a shell is available)

MCP injects its tool schema into model context every turn; a CLI call costs ~0 standing tokens. Install and configure once:

    npx @bcontext/cli login --token bctx_live_…   # or: export BCONTEXT_TOKEN / BCONTEXT_URL / BCONTEXT_WORKSPACE

`bcontext` (alias `bx`) commands:

    bx ask "question"           synthesized answer, claims cited [N], sources with /n/<id>#<block> refs
    bx search / get / tree       retrieval + node reads (links, dependencies, attachments)
    bx unblocked                 tasks ready to start (no undone blockers)
    bx changes --since <ts>      incremental change feed (cheap re-sync)
    bx create / update / toggle / link / unlink / attach
    bx update <id> --if-updated-at <ts>    optimistic concurrency (409 on conflict)
    bx mcp <tool> '<json>'       escape hatch to any MCP tool

## MCP

Streamable HTTP MCP server at https://app.bcontext.dev/mcp. Add to Claude Code / Cursor / Claude Desktop mcp.json with the same bearer token.

Tools: search_nodes, get_node, create_node, update_node, delete_node, list_nodes, ask_rag, toggle_checklist_item, link_nodes, unlink_nodes, attach_file, list_changes, list_skills, run_skill, list_workspaces, ping.

## Limits

- Read scopes: 120 req/min per token
- Write scopes: 60 req/min
- Chat: 30 req/min
- 429 Retry-After is enforced

## Conventions

Structure node content with H2 (##) headings — each section becomes a stable, addressable block. References use `/n/<node_id>#<block_id>` (e.g. `/n/abc#vision`), where `block_id` is the slug of the heading text.

Concurrency: pass `if_updated_at` (the updated_at you last read) when patching content — a 409 means another session wrote first; re-fetch, rebase, retry. Dependencies are typed edges (link_nodes / bx link, relation blocked_by), not prose; `unblocked` filters answer "what can I start now".