Documentation

Quick Start

Five easy pours from empty glass to agents on tap.

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

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": "streamableHttp",
      "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": "streamableHttp",
      "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.

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.

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.

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.

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...

Roles & Permissions

Organizations use role-based access control with two roles:

FAQ & Troubleshooting