MCP server
Connect BrewForge to Claude, ChatGPT, Cursor, VS Code and other AI assistants through the BrewForge MCP server: setup, sign-in with OAuth or an API token, toolsets, safety and troubleshooting.
BrewForge runs an MCP server. Add it to an AI assistant and the assistant can work with your brewing data the way you do in the app: look up a brew, plan the next batch, log a gravity reading, check what's on tap, find out which ingredients you're short of.
https://brewforge.sh/api/mcpEvery tool of the MCP server is also an action of the actions API, with the same name, parameters and results. The tool reference lists all of them.
Pro plan
The MCP server and the API need the Pro plan or higher. You can connect an assistant on any plan, but every tool call returns TIER_REQUIRED until your account is on Pro.
What an assistant can do
Everything you do with your own brewing data in the app: recipes and brews from idea to packaging, brew day measurements, fermentation readings, ratings and evaluations, devices, the cellar, packaged stock, tap lists and labels, your ingredient inventory, orders and the planner, profiles and styles, custom fields, preferences, the calendar, calculators, imports and exports, the community, feedback and support tickets.
What it can't do: change your password, email, sessions or API tokens, delete your account, see or change payment details or your plan, or use admin features. The consent screen says so too.
Connect your assistant
There are two ways to sign in:
- OAuth sign-in (recommended): you add the URL, the assistant opens BrewForge in your browser, you sign in and click Allow. No token to copy, and you can disconnect the app any time under Settings → Integrations → API tokens → Connected apps.
- API token: for clients without OAuth, or scripts. Create a token under Settings → Integrations → API tokens and send it as
Authorization: Bearer bfk_…header.
In claude.ai or the Claude desktop app:
- Open Settings → Connectors and click Add custom connector.
- Name it "BrewForge" and enter the URL
https://brewforge.sh/api/mcp. - Click Connect. BrewForge opens: sign in if you aren't, check what the app may do and click Allow.
In a chat, turn the connector on in the tools menu and ask away.
With OAuth:
claude mcp add --transport http brewforge https://brewforge.sh/api/mcpThen run /mcp in a Claude Code session, pick brewforge and Authenticate. Your browser opens BrewForge; sign in and click Allow.
With an API token instead:
claude mcp add --transport http brewforge https://brewforge.sh/api/mcp \
--header "Authorization: Bearer bfk_your_token_here"Where your ChatGPT plan allows custom connectors (MCP servers), create one with the URL https://brewforge.sh/api/mcp and OAuth as authentication. ChatGPT opens BrewForge to sign in; click Allow.
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"brewforge": { "url": "https://brewforge.sh/api/mcp" }
}
}Cursor asks you to sign in to BrewForge the first time. To use an API token instead, add "headers": { "Authorization": "Bearer bfk_your_token_here" } next to url.
Add the server to .vscode/mcp.json in your project (or run MCP: Add Server from the command palette):
{
"servers": {
"brewforge": { "type": "http", "url": "https://brewforge.sh/api/mcp" }
}
}VS Code opens BrewForge to sign in when you start the server. For an API token, add "headers": { "Authorization": "Bearer bfk_your_token_here" }.
Any MCP client that speaks Streamable HTTP works. The server is stateless: every request is a POST with a JSON-RPC message, answered with JSON (no sessions, no event stream).
- OAuth 2.1 with discovery: the client gets a
401with aWWW-Authenticateheader pointing athttps://brewforge.sh/.well-known/oauth-protected-resource/api/mcp, registers itself (dynamic client registration) and signs you in with PKCE. - Or send an API token as
Authorization: Bearer bfk_….
OAuth sign-in in detail
- The app asks for read (see your data) or write (see and change it). The consent screen at brewforge.sh shows the app's name, what it will be able to do, and where you go back to afterwards.
- Access tokens last one hour; the app renews them with a refresh token, which lasts 30 days and changes on every use. As long as you use the app at least once a month, you stay connected.
- Settings → Integrations → API tokens lists your Connected apps with when they were connected and last active, and whether they may read or also change data. Click one and Disconnect to cut it off at once.
- OAuth connections always get access to every area. To limit an assistant to some areas (only brews, only inventory, …), use an API token with area scopes.
Choose the tools
By default the server offers all tools (more than 100). Assistants work better with fewer, so you can narrow them with the URL:
| URL | Tools |
|---|---|
https://brewforge.sh/api/mcp | All toolsets |
https://brewforge.sh/api/mcp?toolsets=brewing,cellar | Only these toolsets (plus core) |
https://brewforge.sh/api/mcp?read_only=1 | Only tools that read; nothing can be changed |
https://brewforge.sh/api/mcp?toolsets=inventory&read_only=1 | Both combined |
The toolsets:
| Toolset | Covers |
|---|---|
core | get_started: account, plan, units, enabled features and a map of the other tools. Always on. |
brewing | Recipes and brews, brew day, fermentation readings, evaluations and devices |
cellar | Cellar vessels, packaging, packaged stock, tap lists and labels |
inventory | Ingredient stock, ingredient catalog, packages, orders and the planner |
setup | Profiles, styles, custom fields, preferences, calendar, analysis, calculators, imports and exports |
community | Community, recipe sharing, feedback, support tickets, inbox and changelog |
An API token also hides the tools its scopes don't allow: a token with only brews:read sees only the tools that read brews.
Example prompts
Safety
- Deleting needs confirmation. Tools that delete or undo things (marked destructive in the tool reference) change nothing on the first call. They return what would be removed, and only a second call with
confirm: truedoes it. Assistants are told to show you that preview and ask before confirming. - Public posts. Feedback posts, replies, support tickets and community interactions are visible to other people or to the BrewForge team. Let the assistant show you the text and confirm before it posts.
- Read-only first. Trying it out? Connect with
?read_only=1, or give the API token only read scopes. - Disconnect apps you no longer use under Connected apps, and delete API tokens you no longer need.
Limits
Tool calls share one rate limit with the actions API: 600 requests per hour and 20,000 per 30 days per account. Every request to the MCP server counts, including the client listing the tools. See Rate limits.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
401 / UNAUTHORIZED, or the client says it needs to authenticate | No token, an unknown or deleted API token, or the OAuth connection was disconnected or expired | Authenticate again from the client (in Claude Code: /mcp → Authenticate), or check the API token |
TIER_REQUIRED | Your account isn't on Pro or higher, or a tool needs a plan feature your plan doesn't include | Upgrade your plan; the message names the plan that's needed |
SCOPE_REQUIRED | The API token lacks the scope for this tool | Add the scope to the token under Settings → Integrations → API tokens; the token value stays the same |
FORBIDDEN … "not enabled on this MCP connection" | The tool's toolset isn't in ?toolsets=, or the connection is ?read_only=1 | Change the URL in the client |
RATE_LIMITED | More than 600 requests in an hour (or 20,000 in 30 days) | Wait the seconds given in the message |
NOT_FOUND / AMBIGUOUS_REFERENCE with candidates | A brew, recipe or other thing wasn't found or matches several | Assistants retry with one of the listed ids by themselves; otherwise say which one you mean |
All errors and what they mean: Actions API → Errors.