# Brain Colonies

> A wisdom-orchestration layer for AI agents. Brain Colonies (BC) gives any
> MCP-compatible client a per-turn "check-in" (drift, missing perspectives,
> pending reflections) plus on-demand consults with a colony of specialist
> brains that hold your project's memory and knowledge.

This file is a machine-readable guide for AI agents and tooling. If you were
asked to "add Brain Colonies MCP," everything you need is below — you do NOT
need to render the JavaScript docs site to find it.

## MCP endpoint (this is the server address)

- URL (Streamable HTTP transport): https://mcp.braincolonies.com/mcp
- Auth: HTTP header `Authorization: Bearer <API_KEY>`
- API keys start with `bc_live_` and are created at https://braincolonies.com/settings/developers
- `mcp.braincolonies.com` is a DNS-only subdomain that points straight at the
  AWS API Gateway behind the server — it bypasses the braincolonies.com CDN and
  its bot protection, so it is reachable from any host or IP (including agents
  and CI) once you have the URL + key.
- `initialize` and `tools/list` are open; `tools/call` requires a paid plan
  (Pro, Studio, or Enterprise).
- Fallback URL (same server, if the subdomain ever fails to resolve):
  https://ma3yuktnyh.execute-api.us-east-1.amazonaws.com/mcp

## Add it to a client

Claude Code (CLI), user scope so the key never lands in a repo:

```
claude mcp add --transport http brain-colonies \
  https://mcp.braincolonies.com/mcp \
  --header "Authorization: Bearer bc_live_YOUR_KEY" -s user
```

Codex CLI (reads the key from an env var):

```
codex mcp add brain-colonies \
  --url https://mcp.braincolonies.com/mcp \
  --bearer-token-env-var BRAINCOLONIES_API_KEY
```

JSON config (Claude Desktop, Cursor, Cline, VSCode, etc.):

```json
{
  "mcpServers": {
    "brain-colonies": {
      "url": "https://mcp.braincolonies.com/mcp",
      "headers": { "Authorization": "Bearer bc_live_YOUR_KEY" }
    }
  }
}
```

MCP servers connect at client start-up. After adding, fully RESTART the client
(quit and reopen — a reload is not enough) before the BC tools appear.

## Tools

- bc.checkIn — per-turn drift signal, missing perspectives, pending reflections
- bc.consult — single-brain consult routed through your colony
- bc.colony.list — list colonies + brains
- bc.brain.add — add a brain to a colony
- bc.context.fetch — retrieve relevant context from knowledge or memory
- bc.knowledge.upload — add a document to a colony's knowledge
- bc.knowledge.list — list a colony's knowledge

## Machine-readable manifest

- https://braincolonies.com/.well-known/mcp.json

## Docs (raw markdown — fetchable without running JavaScript)

Every docs page has a raw-markdown twin at the same path + ".md". Fetch
these directly; the no-extension URLs are a JavaScript-rendered SPA and
return an empty shell to non-browser clients.

- Quickstart (MCP):   https://braincolonies.com/docs/quickstart/mcp.md
- MCP overview/ref:    https://braincolonies.com/docs/mcp.md
- Tool: bc.checkIn:    https://braincolonies.com/docs/mcp/bc-checkin.md
- Tool: bc.consult:    https://braincolonies.com/docs/mcp/bc-consult.md
- Docs index:          https://braincolonies.com/docs/index.md

Human (rendered) versions live at the same URLs without ".md".