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 with a Bearer token for authentication.

Generating API Keys

API keys authenticate your AI agents with the MCP server. 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.

{
  "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. The general pattern is:

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 key requirements are: the URL must point to the /mcp endpoint, and the Bearer token must be included in the Authorization header.

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