Your knowledge, shared. Connected in five minutes.

Start here

Quickstart — your first connection

Zero to a working, verified agent connection in about five minutes. Four steps, one command, no credit card.

your-repo/
├── conventions.md
└── skills/
    ├── code-style/
    │   └── SKILL.md
    └── testing/
        └── SKILL.md

Start here

The mental model

Three primitives, one connection. Sixty seconds of theory before the reference.

Connect

CLI reference — npx brewale

The installer the quickstart just ran, in full. It shows you the exact bytes before writing anything, and re-running is idempotent.

Commands

Flags

What we write where

Connect

Manual setup — any MCP client

For clients the CLI doesn't cover, and for people who prefer editing JSON themselves.

// ./.mcp.json (project scope)
{
  "mcpServers": {
    "brewale": {
      "type": "http",
      "url": "https://mcp.brewale.dev/mcp"
    }
  }
}

// ./.mcp.json — env-var reference, never the raw token
{
  "mcpServers": {
    "brewale": {
      "type": "http",
      "url": "https://mcp.brewale.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${BREWALE_MCP_TOKEN:-}"
      }
    }
  }
}

Project scope lives in .mcp.json at the repo root. User scope goes through `claude mcp add --scope user` into ~/.claude.json — there is no ~/.claude/mcp.json.

To scope a connection to a project, append ?project_id=owner/repo to the URL — see Projects.

Connect

Authentication

Two ways in: OAuth 2.1 for humans in editors, org-scoped API keys for CI and clients without OAuth support. Both arrive on the Authorization header.

OAuth 2.1 (recommended)

1. The client hits /mcp without credentials and gets a 401 with a WWW-Authenticate challenge.
2. It discovers the authorization server via /.well-known metadata.
3. Dynamic Client Registration (RFC 7591) means no pre-registration — any client self-onboards from just the URL.
4. Your browser opens: sign in, pick the organization, grant consent.
5. The code is exchanged for short-lived JWTs verified via JWKS, refreshed via offline_access.

Scopes: mcp:read and offline_access. No long-lived secret is ever stored in an editor config.

API keys

Minted under Settings → API Keys: name, optional expiry, lore-mcp_ prefix. Shown exactly once, hashed at rest, scoped to one organization, revocable individually.

Authorization: Bearer lore-mcp_your-api-key

Who can cut what, instantly

Connect

Service accounts

Machine identities that authenticate to MCP on behalf of your org — for shared bots, CI agents, and review automation, without tying the connection to a person.

Create them under Settings → Service accounts: a name, a visibility (private to the creator or org-wide so admins manage it), and bearer tokens with optional expiry. They authenticate via token or via the OAuth select-org “authorize as” flow. Each account keeps an authentication log and shows up in analytics like a member, so automated usage stays attributable.

Skills & conventions

Conventions

The always-on half of the content model: one conventions.md at the repo root (or under your configured base path), served whole by get_conventions — which well-configured agents call at session start and before edits. That's exactly what the CLI's instruction block enforces.

Every push creates a new version tied to the commit SHA — history and one-click unpublish live in the app under Conventions.

Not loading? Check the file lives at the configured base path and review the sync history under Settings → GitHub — or jump to Troubleshooting.

Skills & conventions

Skills & skill bundles

The on-demand half: reusable knowledge documents your agents pull only when relevant.

Anatomy

Each skill is a skills/{slug}/SKILL.md with optional YAML frontmatter — name, description, and category. The description is what agents see in list_skills, so write it as a trigger: “Use when…”.

---
name: "Release checklist"
description: "Use when preparing or verifying a production release."
category: "devops"
---

Your skill content in markdown…

Categories: code_style, testing, architecture, git_workflow, security, performance, api_design, documentation, devops, other.

Bundles

A skill directory can also carry references/, scripts/, and templates/. Agents fetch individual bundle files on demand via get_skill_file — big skills stay cheap, because only what's needed enters the context window.

skills/
└── release-checklist/
    ├── SKILL.md
    ├── references/
    │   └── rollout-order.md
    ├── scripts/
    │   └── verify.sh
    └── templates/
        └── announcement.md

Lifecycle & per-user control

• Push → auto-sync → published. Per-version history by commit SHA; unpublish from the UI without touching the repo.
• “Enabled for me”. Every member has a per-skill toggle — disabled skills disappear from that member's list_skills. A personal preference, not an org-wide state.
• Agents can also draft new skills — see Agent-authored proposals — and per-skill analytics show whether each one earns its keep.

Personal skills

Skills don't have to belong to the org. Ask your agent for a private skill and it calls create_skill with visibility: "personal" — the skill is tied to your account instead, and you review and publish it yourself under Account → My skills.

• Only your agents see it. Personal skills are served exclusively to your own connections, listed as p:{slug} in list_skills — never to other members.
• Available in all your orgs. One personal skill follows you across every organization you belong to, with a per-org switch to turn it off where it doesn't fit.
• Brewale-only. Personal skills are never synced to a GitHub repo — download any of them as a zip from Account → My skills.

Skills & conventions

Agent-authored skills & conventions

Agents draft, humans publish. The propose → review → publish loop is the first “aha” after connecting.

Starter prompt

We just solved <X>. Propose a Brewale skill capturing how — call skill_authoring_guide first, then create_skill.

Skills & conventions

Projects — scope what each agent sees

Opt-in: any org admin flips it on under Settings → Organization. One org, many repos, different standards — the right context flows to the right codebase.

• Scope in git. Skills and conventions declare scope: general | project in their frontmatter. general content is always served; a project item is served only to connections scoped to a project it's attached to — attachments are managed in the app.
• Scope the connection. Append ?project_id=owner/repo to the MCP URL. npx brewale derives this from the git remote automatically (--project-id / --no-project-id to override), and any tool call can pass a per-call project_id override.
• Agent-side tools (available when Projects is on): register_project registers a new owner/repo key, search_projects finds existing ones. The Projects page in the web app lists them all.

Skills & conventions

GitHub sync & repository structure

Connect (optional)

Settings → GitHub → install the Brewale GitHub App → pick a repository (switch anytime) with an optional base path. No repo? Skip it — author over MCP, publish in Brewale, and export everything as markdown from Settings → GitHub whenever you want.

Sync

Pushes to the default branch sync incrementally via webhook — only changed files are processed. Sync Now forces a full manual pass, and a sync history shows the status, commit SHA, and any errors for every run.

Publishing & version history

The publish gate and commit-SHA pinning are the core control primitive: agents only ever see published content, and every published version maps to exactly one commit.

Repository layout

<base-path>/
├── conventions.md
└── skills/
    ├── code-style/
    │   └── SKILL.md
    └── release-checklist/
        ├── SKILL.md
        ├── references/
        ├── scripts/
        └── templates/

SKILL.md frontmatter (all fields optional): name (defaults to the slug), description, category (defaults to “other”), and scope when Projects is enabled.

Approving an agent proposal commits through this same connection — one pipeline for human- and agent-written content.

Run your org

Members, roles & invitations

• Invitations. Settings → Members → invite by email. The invitee gets a link, signs up (or in) and lands in the org — works with Google sign-in too.
• Ownership transfer. Owner-only, under Settings → Members.
• Removal. Removing a member revokes their org MCP access.
• Multiple orgs. One account can belong to several orgs. The org switcher picks context in the web app; OAuth consent picks which org a connection serves.

Run your org

Analytics

The quickstart answers “is it connected?” — analytics answer “is the knowledge actually being used?”

• Org overview. 30-day summary cards, a calls-over-time chart, top skills, and a per-member table with drill-in to an individual member's usage.
• Per-skill analytics. From any skill's page: total calls, a 30-day trend, and top callers — the feedback loop for curation. Skills nobody calls need better descriptions or retirement; heavily-called skills deserve investment.
• Attributable automation. Service accounts appear alongside members, so automated usage is never a blind spot.

Run your org

Billing & trial

Plain, verifiable billing facts — the same ones the pricing page commits to.

• Per-seat subscription, billed via Polar — checkout, invoices, and receipts all run through it.
• 14-day free trial, no card. The clock starts on your org's first MCP call, not at signup — setup time is untimed.
• Unused trial days carry over to checkout: subscribing early never costs you trial time.
• Seats reconcile automatically as members join and leave. There is no seat list to manage.
• Inactive members are not billed as seats — see Members & roles for what the toggle does.
• Service accounts are never billed as seats.
• Billing managers: under Settings → Billing, admins choose who receives invoices and billing email — including addresses like finance@ that never log in. Polar emails all of them.
• Payment failure: we warn, we don't cut off. There is a grace period before anything is restricted.
• An expired trial without a subscription is the one state that pauses MCP access. Your content, repo connection, and web access are untouched — subscribing resumes service immediately.

Current price: brewale.dev/pricing.

Run your org

Account security

Everything here is self-service — protect the account, and kill access instantly when you need to.

Two-factor authentication

TOTP with any authenticator app. Setup generates one-time backup codes — store them outside the authenticator; they're your way back in if you lose the device.

Sign in with Google

One-click login and signup, plus linking Google to an existing email/password account from account settings.

Kill switches

Token hygiene

• Prefer OAuth for humans in editors — nothing long-lived to leak.
• Give CI tokens an expiry date when you mint them.
• Revoke tokens you no longer use under Settings → API Keys.
• Tokens are hashed at rest and shown exactly once at mint — treat the copy you take as the only copy.

Reference

MCP tool reference

The complete tool surface your agents get through the Brewale connection — twelve tools in three groups.

The chips describe how each tool behaves: read tools return published content, proposes tools only ever create drafts for human review.

Every tool is org-scoped by the authenticated connection. There is no tool that mutates published content or your repository directly.

Reference

Troubleshooting & FAQ

Ordered by frequency. The first answer is almost always npx brewale status.