MCP Server

BrewHoard as an MCP server — expose your collection to AI assistants via the Model Context Protocol with OAuth 2.1 authentication.

Overview

BrewHoard exposes a Model Context Protocol (MCP) server at POST /api/mcp using the Streamable HTTP transport (protocol version 2025-03-26). This lets AI assistants like Claude Desktop search your collection, rate beers, and more — all scoped by OAuth permissions you grant.

Prerequisites

A BrewHoard account
An MCP-compatible client (e.g. Claude Desktop, MCP Inspector)

Authentication

Every MCP request requires a valid OAuth 2.1 Bearer access token obtained through the Authorization Code + PKCE flow:

Register — POST /oauth/register → receive client_id
Authorize — Redirect user to /oauth/authorize → user logs in and approves scopes
Token — POST /oauth/token → exchange auth code for access_token
Call — POST /api/mcp with Authorization: Bearer <access_token>

See the OAuth 2.1 guide for full details.

MCP Methods

`initialize`

Handshake with the server.

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

Response:

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "BrewHoard MCP", "version": "1.0.0" }
  }
}

`tools/list`

List all available tools.

`tools/call`

Execute a tool by name. Each tool requires specific OAuth scopes.

Available Tools

Tool	Required Scopes	Description
`search_beers`	`beers:search`	Search beers by name, brewery, or style
`get_beer_details`	`beers:read`	Get detailed info about a specific beer
`get_beer_styles`	`beers:styles`	List available beer styles
`list_collection`	`collection:read`	List beers in your collection
`add_to_collection`	`collection:write`	Add a beer to your collection
`remove_from_collection`	`collection:write`	Remove a beer from your collection
`consume_beer`	`collection:consume`	Mark a beer as consumed
`get_collection_history`	`collection:history`	Get consumption history
`rate_beer`	`ratings:write`	Submit or update a beer rating
`get_recommendations`	`recommendations:read`	Get personalized beer recommendations
`get_collection_stats`	`analytics:read`	Get collection statistics
`get_consumption_analytics`	`analytics:read`	Get consumption trends
`export_collection`	`export`	Export collection as CSV or JSON

Tool Details

search_beers

JSON

{
  "name": "search_beers",
  "arguments": {
    "query": "IPA",
    "limit": 10
  }
}

get_beer_details

JSON

{
  "name": "get_beer_details",
  "arguments": {
    "beerId": "uuid-of-beer"
  }
}

list_collection

JSON

{
  "name": "list_collection",
  "arguments": {
    "status": "available",
    "limit": 25,
    "offset": 0
  }
}

add_to_collection

JSON

{
  "name": "add_to_collection",
  "arguments": {
    "beerId": "uuid-of-beer",
    "quantity": 2,
    "notes": "Cellared vintage"
  }
}

consume_beer

JSON

{
  "name": "consume_beer",
  "arguments": {
    "itemId": "uuid-of-collection-item",
    "rating": 4.5,
    "notes": "Excellent with age"
  }
}

rate_beer

JSON

{
  "name": "rate_beer",
  "arguments": {
    "beerId": "uuid-of-beer",
    "rating": 4,
    "notes": "Great hop profile"
  }
}

get_recommendations

JSON

{
  "name": "get_recommendations",
  "arguments": {
    "limit": 5,
    "style": "stout"
  }
}

get_consumption_analytics

JSON

{
  "name": "get_consumption_analytics",
  "arguments": {
    "period": "month"
  }
}

export_collection

JSON

{
  "name": "export_collection",
  "arguments": {
    "format": "csv",
    "status": "all"
  }
}

Rate Limiting

MCP requests are rate-limited per OAuth client to prevent abuse. Exceeding the limit returns a JSON-RPC error:

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Error Codes

Code	Meaning
`-32700`	Parse error — invalid JSON
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params
`-32001`	Unauthorized — missing or invalid Bearer token
`-32002`	Rate limit exceeded
`-32003`	Insufficient scopes

Testing with MCP Inspector

Create an mcp.json config:

JSON

{
  "mcpServers": {
    "brewhoard": {
      "type": "streamable-http",
      "url": "http://localhost:5173/api/mcp"
    }
  }
}

Launch the Inspector against this config and walk through the OAuth flow.

Next Steps

OAuth 2.1 Guide — Authorization server setup
API Reference — REST API documentation
Authentication — Session and API key auth