Documentation

Quick Start

Five easy pours from empty glass to agents on tap.

Quick Setup — npx brewale

One command connects your coding agents to Brewale. It detects Claude Code, the OpenAI Codex CLI, Cursor, VS Code, and Zed, writes the MCP server config for each (OAuth 2.1 by default, or an API token), and — with separate consent — adds a conventions block to your CLAUDE.md / AGENTS.md so agents consult Brewale automatically.

npx brewale@latest

Nothing is written without showing you the exact change first, and re-running is idempotent. npx brewale status gives a read-only health report of your setup, and npx brewale uninstall removes everything it added.

Connecting to the MCP Server

The Model Context Protocol (MCP) is an open standard that lets AI agents access external tools and data. Brewale runs an MCP server that pulls your org's skills and conventions from the cellar and serves them to any MCP-compatible client—no flat context here.

The server supports Streamable HTTP transport. Your agent connects by making HTTP requests to your server's /mcp endpoint and authenticates with either OAuth 2.1 (preferred) or an API key Bearer token. See Authentication below for details.

Authentication

The MCP server accepts two forms of credentials on the Authorization header. OAuth 2.1 is the preferred method — it gives each agent a short-lived, scoped access token tied to a real user session, with refresh and revocation handled by the server. API keys remain supported for clients that don't speak OAuth or for scripted / headless setups.

OAuth 2.1 (preferred)

Brewale advertises an OAuth 2.1 authorization server at /.well-known/oauth-protected-resource and supports Dynamic Client Registration (RFC 7591), so MCP-native clients can self-onboard from just the server URL — no manual client ID / secret setup. The typical flow:

1. Agent makes a request to /mcp without credentials and gets a 401 with a WWW-Authenticate challenge.
2. Client registers dynamically, then opens the authorization URL in your browser.
3. You sign in, pick the organization, and grant consent.
4. Client exchanges the authorization code for an access token and (with offline_access) a refresh token.
5. Agent sends the JWT as Authorization: Bearer <jwt> on every subsequent request. The server validates it against the JWKS.

Supported scopes: mcp:read (default) and offline_access (refresh tokens).

API key (Bearer token)

For clients without OAuth support — CI scripts, older IDE plugins, quick local tests — generate an API key in Settings → Tokens and send it on the Authorization header:

Authorization: Bearer lore-mcp_your-api-key

Keys are prefixed with lore-mcp_, hashed at rest, scoped to one organization, and can be revoked at any time. See Generating API Keys below.

Generating API Keys

API keys authenticate your AI agents with the MCP server when OAuth isn't an option. Each key is scoped to your organization.

1. Navigate to Settings → Tokens in the web app
2. Click Create Token, give it a name, and optionally set an expiration time
3. Copy the token immediately — it's only displayed once

Service Accounts

Service accounts are machine identities for agents that run without a human in the loop — CI pipelines, scheduled jobs, or shared automation. Instead of tying an MCP connection to a person's session, the agent authenticates as the account, so its activity is attributed to the account rather than to you.

Manage them under Settings → Service Accounts. Click Create Service Account, give it a name and optional description, and choose its visibility:

• Private — only you can manage it.
• Org-wide — admins manage it on behalf of the organization.

Each account has its own detail page where you can mint bearer tokens (with an optional expiry), grant access to custom MCP integrations, review its usage analytics, and see an authentication log of who acted as the account and how. Revoking the account disables all of its access at once.

Connecting with Claude Code

Add Brewale to your Claude Code configuration. You can configure it globally or per-project.

OAuth 2.1 (preferred)

Claude Code handles the OAuth handshake automatically — just point it at the server and sign in when the browser opens.

{
  "mcpServers": {
    "brewale": {
      "type": "http",
      "url": "https://mcp.brewale.dev/mcp"
    }
  }
}

API key (Bearer token)

If you'd rather use a long-lived API key — for headless setups, shared machines, or clients where OAuth is inconvenient:

{
  "mcpServers": {
    "brewale": {
      "type": "http",
      "url": "https://mcp.brewale.dev/mcp",
      "headers": {
        "Authorization": "Bearer lore-mcp_your-api-key"
      }
    }
  }
}

Replace lore-mcp_your-api-key with your actual API key from Settings → Tokens.

Connecting with Other MCP Clients

Any MCP client that supports Streamable HTTP transport can connect to Brewale.

OAuth 2.1 (preferred)

Clients with OAuth support only need the server URL — they discover the authorization server via /.well-known/oauth-protected-resource and register dynamically.

Server URL:  https://mcp.brewale.dev/mcp
Transport:   Streamable HTTP (POST)
Auth:        OAuth 2.1 (discovered via /.well-known/oauth-protected-resource)

API key (Bearer token)

For clients without OAuth support:

Server URL:  https://mcp.brewale.dev/mcp
Transport:   Streamable HTTP (POST)
Auth Header: Authorization: Bearer lore-mcp_your-api-key

Consult your MCP client's documentation for the specific configuration format. The URL must point to the /mcp endpoint either way.

Custom MCP Integrations

Beyond skills and conventions, Brewale can proxy your own MCP servers to your agents — so a single connection to Brewale also exposes the tools of any third-party or in-house MCP server you add. An admin first enables the feature under Settings → Custom MCP.

Adding an integration

Click Add integration and configure:

• Name & slug — the slug (2–32 chars, lowercase) identifies the server's tools to agents.
• Server URL — the remote MCP endpoint Brewale connects to.
• Auth type — Bearer token, OAuth (DCR), or No auth.
• Auth mode — shared org credentials, or per-member (each member supplies their own). OAuth is always per-member.
• Access control — a single org-wide ACL, or a per-user ACL with optional read/write/delete ceilings.

Integrations start as a draft. Once published, Brewale discovers the server's tools and lists them in a table where you can toggle individual tools on or off and review their read / write / delete classification.

Skills

Skills are reusable knowledge documents that your AI agents can fetch on demand. They typically describe patterns, workflows, or domain-specific instructions — for example, how to write tests in your project, how to structure API endpoints, or how to use a specific library.

Managing skills

Skills are managed as files in your connected GitHub repository. Each skill lives in its own directory under skills/ as a SKILL.md file with YAML frontmatter. When you push to your default branch, Brewale automatically syncs the changes.

The web UI lets you browse skills, view their content, see version history, and control their publish status — but all editing happens in your repository.

How agents use skills

When an agent connects, the MCP server lists all available skills with their slugs and descriptions. The agent calls list_skills to see what's available, then get_skill("slug") to fetch the full content of a relevant skill. Skills are fetched on demand — the agent decides which ones are relevant to the current task.

Enabling skills per user

On the Skills page each published skill has an Enabled for me toggle. This controls whether that skill is offered to your own agent sessions — it's a personal preference, not an org-wide publish state. Turning a skill off for yourself doesn't affect teammates.

Skill categories

Skills can be organized with a category field in their frontmatter. Available categories: code_style, testing, architecture, git_workflow, security, performance, api_design, documentation, devops, other.

Agent-authored Skills

Agents don't just consume skills — they can write them. From an MCP session an agent can call create_skill to draft a new skill or update_skill to propose changes to an existing one. Nothing reaches your agents automatically; every proposal goes through review first.

The review flow

1. Proposed — the agent submits a draft. It appears under Skills → Proposals, visible only to the proposer and any invited reviewers.
2. Review — open the proposal to see the rendered content and, for edits, a diff against the current version. Invite other members to review from the proposal page.
3. Approve & publish — approving commits the skill to your connected GitHub repository and publishes it to all agents in one step. Reject discards the draft instead.

Conventions

Conventions are your organization's coding standards and rules. Unlike skills, conventions are automatically loaded at the start of every agent session — the agent doesn't need to decide whether to fetch them.

Conventions are managed as a single conventions.md file in the root of your configured base path in your GitHub repository. Use conventions for things that should always apply: naming conventions, commit message formats, code review criteria, architectural rules, or language-specific style guides.

Agent-authored Conventions

Just like skills, agents can propose conventions. From an MCP session an agent can call create_convention to draft a new convention or update_convention to propose changes to an existing one (including your root conventions.md). Nothing reaches your agents automatically; every proposal goes through review first. Agents can call convention_authoring_guide for the authoring rubric.

The review flow

1. Proposed — the agent submits a draft. It appears under Conventions → Proposals, visible only to the proposer and any invited reviewers.
2. Review — open the proposal to see the rendered content and, for edits, a diff against the current version. Invite other members to review from the proposal page.
3. Approve & publish — approving commits the convention to your connected GitHub repository (the root conventions.md, or conventions/<slug>.md for a named convention) and publishes it to all agents in one step. Reject discards the draft instead.

Projects

Projects scope which skills and conventions an agent receives to the repository it is working in. A project is a key shaped like owner/repo that skills and conventions get attached to. Enable Projects from Settings → Organization.

Scope frontmatter

Each skill and convention declares a scope in its git frontmatter — either general (the default) or project. A general item is served to every agent. A project item is served only to agents working in a project it is attached to. Scope lives in git — the web UI only records which projects a scope: project item is attached to.

Connecting a project

Set the project on your MCP connection with a ?project_id=owner/repo query parameter, so every call from that connection is scoped to it. Any single tool call may also pass a project_id to override the connection value for that call.

Registering & finding projects

Agents can create a project over MCP with the register_project tool (idempotent on the key), and discover existing project keys with search_projects. You can also create, rename, and delete projects from the Projects page in the web app.

Publishing & Unpublishing

When you push changes to your GitHub repository, Brewale syncs the content and automatically publishes the new version. Agents only see published content.

How it works

1. Sync — Push to your default branch and Brewale automatically picks up the changes via webhook. Each sync creates a new version linked to the commit SHA.
2. Auto-publish — New versions from GitHub sync are published automatically. The MCP server's in-memory cache updates instantly — agents see the new content immediately.
3. Unpublish — From the web UI, you can unpublish a skill or convention to remove it from agent access without deleting it. You can republish later.

Version history

Every sync creates a version snapshot linked to the Git commit. You can view previous versions and their content in the version history panel on each skill or convention's detail page.

GitHub Integration

GitHub is the source of truth for all your skills and conventions. Brewale syncs content from your repository automatically on every push to your default branch.

Connecting a repository

1. Go to Settings → GitHub (admin only)
2. Click Connect GitHub Repository to install the Brewale GitHub App
3. Select the repository you want to connect
4. Brewale runs an initial sync to import all existing skills and conventions

Base path

By default, Brewale looks for files at the root of your repository. If your skills and conventions live in a subdirectory (e.g., .brewale or docs/ai), set the base path in the GitHub settings. Changing the base path triggers a full re-sync.

Manual sync

You can trigger a manual sync at any time from Settings → GitHub using the Sync Now button. This does a full repository sync regardless of what has changed. The sync history table shows the status, commit SHA, and any errors for each sync.

How syncing works

• Push events — Brewale receives a webhook on each push to your default branch and processes only the changed files (incremental sync).
• New/modified files — If the content differs from the current version, a new version is created and published automatically.
• Deleted files — Removing a skill file from your repo unpublishes it in Brewale (the history is preserved).
• No-op on unchanged content — If a file is touched but the content is identical, no new version is created.

Repository Structure

Brewale expects the following file structure in your connected repository, relative to the configured base path:

<base-path>/
├── conventions.md
└── skills/
    ├── code-style/
    │   └── SKILL.md
    ├── testing/
    │   └── SKILL.md
    └── api-patterns/
        └── SKILL.md

conventions.md

A single markdown file at the base path root. Its content is returned in full when an agent calls get_conventions. No frontmatter required — just write your conventions in markdown.

skills/{slug}/SKILL.md

Each skill lives in its own directory under skills/. The directory name becomes the skill's slug. Each SKILL.md file uses YAML frontmatter followed by the skill content:

---
name: "Code Style Guide"
description: "TypeScript naming conventions and formatting rules"
category: "code_style"
---

Your skill content in markdown...

Analytics

The Analytics page shows how your agents are actually using Brewale over the last 30 days — so you can see which skills earn their keep and spot the gaps worth filling.

The overview includes:

• Summary cards — total calls, convention reads, skill lookups, and skill listings.
• Calls over time — a 30-day trend.
• Top skills — your most-called skills, ranked.
• Developer activity — a per-member table (service accounts included) with call counts and last-seen times.

Click any member to drill into their own usage, including recent calls. Every call an agent makes — get_conventions, list_skills, and get_skill — is counted here.

Roles & Permissions

Organizations use role-based access control with two roles:

Account & Security

Your Account page is global — it lives outside any organization and manages your personal sign-in and security. Everything here is self-service: you don't need an admin to lock down your own account.

Two-factor authentication

Enable two-factor authentication to require a code from a TOTP authenticator app at sign-in. Click Enable two-factor, confirm your password, scan the QR code (or enter the key manually), then verify a code to activate. You'll be given a set of backup codes — save or download them, as they're your way back in if you lose the device. You can regenerate backup codes or disable 2FA later; both are password-gated.

Sign-in methods

Sign in with email and password or with Google. From the account page you can link or unlink Google to your existing account. If you signed up with Google only and want a password too, set one via the forgot-password flow.

Revoking access

• Disconnect all MCP clients — revokes the OAuth tokens your agents (Claude Code, etc.) use. Each client must re-authorize to reconnect. This takes effect immediately. API keys are managed separately on the Tokens page.
• Sign out everywhere — ends every dashboard session, including the one you're using now.

OAuth access tokens are short-lived (refreshed automatically), so revocation propagates quickly across your agents.

Billing & Plans

Brewale is billed per member seat. Every organization gets a 14-day free trial — no card required — and the trial clock starts on your first MCP call, not at signup, so you don't burn days while setting things up.

Admins manage billing under Settings → Billing, which shows your trial status, current plan, seat count, and renewal date. Subscribe or open the customer portal to update payment details and cancel — checkout and subscription management are handled by Polar.

FAQ & Troubleshooting