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. Archive a convention to stop serving it without losing it, and restore it from the Archived list anytime.

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. Every version has its own link, so you can point a teammate at exactly the one you mean.
• Archive, don't delete. Archiving a skill stops serving it to agents within ~5 seconds and moves it to the Archived list — Restore brings it back with its history.
• In your slash menu. Every skill your agent can use is also an MCP prompt you can run yourself — in Claude Code as /mcp__brewale__{slug}. With local skills they show up as plain /{slug} commands instead.
• “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

Local skills

npx brewale sync writes your skills into each agent's own skills folder. Agents see every skill from the first message of a session, without a tool call to find them, and each skill shows up as a plain /{slug} command.

Set up a computer

Log in once per computer, then sync. Login opens your browser, where you pick an organization and approve the computer. On a machine without a browser, open the link on another device and run the --code command it shows. Run sync from the repository root to also get that project's skills.

npx brewale login
npx brewale sync

Or ask your agent to “update my local skills”. It calls sync_local_skills and runs the one-time npx brewale sync --code … command it gets back — or hands it to you, if its sandbox can't write to your home folder. The code works once and expires after 5 minutes.

Staying up to date

• Claude Code. Setting up local skills with npx brewale adds a session-start hook to ~/.claude/settings.json that syncs quietly each time a session starts.
• Other agents. When skills were added or changed since your last sync, Brewale tells your agent as it loads your conventions, and the agent offers to update. You can also run npx brewale sync any time.

Live or Copy

Admins pick the default under Settings → Organization → Local skills. Anyone can override it for their own computer with npx brewale sync --mode live or --mode copy.

Where the files go

• Only folders for agents found on the computer are written. Zed has no skills folder and keeps using the MCP prompts.
• Project folders are hidden from git through .git/info/exclude — nothing is committed, and teammates' checkouts are untouched.
• Sync only creates, updates and removes folders it wrote itself. A folder of your own with the same name is left alone, with a warning.

Devices

Every computer you log in from is listed under Account → Devices, with its organization and last sync. Its key only works for syncing, not as an MCP connection. Removing a device stops its sync within ~5 seconds; files already written stay on the computer. When a member is removed from the organization, their devices go too: live skills stop loading, while copied files stay on disk.

Skills & conventions

Skills over MCP

Brewale also publishes your skills through the MCP Skills extension, the open standard for serving Agent Skills from an MCP server. An agent that supports it lists your skills and loads them, bundled files included, the way it loads skills from a local folder: no tool call to find them and nothing to sync.

Addresses

• Organization skills: skill://org/{name}/SKILL.md
• Your personal skills: skill://personal/{name}/SKILL.md
• Bundled files sit next to the skill, for example skill://org/{name}/references/checklist.md

{name} is the skill's slug. A slug with characters the standard doesn't allow (capitals, underscores, dots) gets a short suffix so it stays unique.

What agents get

• The same skills as the skill tools. Personal skills reach only you, opted-out skills stay hidden, and project skills appear when the connection is scoped to that project (Projects is enabled per organization).
• Verifiable files. Every file comes with a SHA-256 digest and size, so the agent can check that what it loads is what Brewale listed.
• Current versions. Published changes are served within ~5 seconds; an agent may keep its list of skills for up to a minute before asking again.

Today

Support in agents is still rolling out. Until yours supports it, nothing changes: the skill tools and local skills work as before. In Claude Code, your skills already show up as resources you can attach with @. Reads through this route show in analytics as Skill resource.

Skills & conventions

Agent-authored skills & conventions

Agents draft, humans publish. The propose → review → publish loop is the first “aha” after connecting. It's on by default; admins can switch Agent skill authoring or Agent convention authoring off under Settings → Organization.

Your organization's rules

Admins set how agents write skills and conventions under Settings → Authoring. Changes reach agents within ~5 seconds.

• Quality rubric. Keep Brewale's default, add your own rules on top of it, or replace it with yours. The authoring guides serve the result, and a preview shows exactly what agents get.
• Self-check before submitting. Agents check a draft against the rubric, look for an existing skill or convention that already covers it, and show you what they found before they propose it.
• Approval by someone else. Off by default. When an admin turns it on, authors can't approve their own proposals, so every proposal needs a reviewer. With GitHub sync on, merging the proposal's pull request also publishes it, so require pull request reviews in GitHub too.

Review as a pull request

With GitHub sync on, a proposal can also be reviewed on GitHub. Click Open pull request on the proposal page and Brewale opens one on a brewale/… branch in your connected repo.

• Edit there, see it here. Changes pushed to the pull request show up on the proposal page, which names the commit it's showing.
• Merge & publish in Brewale merges exactly the commit you reviewed — if the branch moved since you loaded the page, reload and review again. Merging on GitHub publishes too; closing the pull request there without merging rejects the proposal.
• Close pull request, keep proposal moves the work back to Brewale with every change made in the pull request.
• While the pull request is open, the author's agent can't send update_* for that item — it's pointed at the pull request's branch instead.

Opening pull requests needs the Brewale GitHub App's Pull requests: read & write permission. If Brewale says it can't open one, accept the App's updated permissions in your GitHub organization settings.

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, or to members who subscribed to that project — attachments are managed in the app or by agents.
• 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 for skills and conventions. Which connectors an agent gets follows the connection URL only.
• Agent-side tools (available when Projects is on): register_project registers a new owner/repo key, search_projects finds existing ones, and attach_to_project / detach_from_project link project-scoped skills and conventions to a project (admins and owners, or every member when an admin allows it). The Projects page in the web app lists them all.
• Always-on projects. Under Settings → Agent content each member picks the projects whose skills and conventions their agents always receive, on top of the connection's project — and can switch off org-wide skills or conventions for themselves. Changes reach agents within ~5 seconds. With connectors on, a third column picks projects whose connectors you always get; those apply once your agent reconnects.

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 — or merges the proposal's pull request, if you opened one. 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

Connectors — your MCP servers

Connect the MCP servers your team already uses and serve their tools through the same Brewale connection — deciding tool by tool what agents may do. Off by default: an admin turns on Allow custom MCP integrations under Settings → Connectors.

Set one up (admins)

1. Settings → Connectors → Add integration: a name, a short name, and the server's public https URL.
2. Choose how people authenticate: one shared credential for the whole org, each person connects their own token, each person signs in with OAuth, or no authentication.
3. Choose who decides what tools can do: one set of rules for everyone, or each person gets their own — optionally only stricter than yours.
4. The connector starts as a draft members can't see. Refresh its tools, allow or deny read, write, and delete, switch off or reclassify individual tools, then Publish.

Use one (members)

• Connectors in the sidebar lists every published connector. Switch on Enabled for me, and sign in or add your token where the connector asks for one. Admins decide whether a connector starts on for everyone.
• Agents call its tools as cmcp__<short name>__<tool>. Changes reach an agent once it reconnects.
• Admins can revoke one person's access to a connector, and restore it, from the connector's page.

Project connectors

With Projects on, a project can have its own connectors — say, a different account per repo. Add them from the project's page with Add connector, or Copy from org to reuse an org connector's setup without its credentials.

• Everyone connects their own account. Project connectors can't use one shared credential.
• The closest one wins. A connection scoped with ?project_id=owner/repo gets that project's connectors. One with the same short name as an org connector replaces it there, so tool names stay the same in every repo. Unscoped connections get org connectors plus those from projects you switched on under Settings → Agent content; if two of those share a short name, each gets its repo name appended.
• Who manages them. Admins manage every project connector. Turn on Let members add project connectors in Settings → Connectors and any member can add one — they manage what they add, it starts switched off for everyone else, and only admins can replace an org connector.

Run your org

Analytics

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

• Org overview. 30-day summary cards compared with the previous 30 days, a calls-over-time chart, top skills, and a per-member table with drill-in to an individual member's usage.
• Agents in use. Sessions from the last 30 days, grouped by the client name each agent reports when it connects (blank names show as “Unknown client”), plus the share of sessions that loaded at least one skill. Session data starts being collected with this feature, so earlier activity doesn't appear, and a session only counts as loading a skill when the client sends the session id back on its later requests.
• How skills are loaded. Successful skill lookups from the last 30 days, split by path: a local skill stub, the get_skill tool, an MCP prompt, or a skill resource read. The same definition of a skill lookup is used for the overview, member, skill and service-account pages. Lookups that found nothing aren't counted.
• Unused skills. Published skills that weren't loaded in the last 30 days, linked to the skill page so you can improve the description or retire them. Skills added in the last week are left out.
• 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.

• Two plans, billed via Polar — checkout, invoices, and receipts all run through it. Solo is a flat monthly price for one developer; Pro is per seat, for teams.
• Solo covers exactly one organization member and every Brewale feature except the team ones: inviting teammates is blocked, and reviewer invites on proposals are hidden. Service accounts still work.
• Upgrade from Solo to Pro in one click under Settings → Billing, or when you try to invite someone. The change is prorated.
• 14-day free trial of Pro, no card. The clock starts on your org's first MCP call, not at signup — setup time is untimed. You pick Solo or Pro when you subscribe.
• Unused trial days carry over to checkout: subscribing early never costs you trial time.
• On Pro, seats reconcile automatically as members join and leave. There is no seat list to manage.
• On Pro, 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 within ~5 seconds.

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

Every Brewale tool your agents get through the connection, in three groups — plus the tools of any connectors your org publishes.

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

Connector tools. Each published connector you've switched on adds its tools as cmcp__<short name>__<tool>, limited to what your org allows. Prompts. Every skill is also an MCP prompt for your slash menu; with local skills it's a plain /{slug} command.

Every tool is org-scoped by the authenticated connection. No Brewale tool publishes content or writes to your repository directly.

Reference

Troubleshooting & FAQ

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