Tutorial: Cocktail Recipes

Food & Drink

Data source: In-memory curated collection

Overview

Cocktail Recipes wraps In-memory curated collection, handling authentication, pagination, and rate limits for you. This tutorial covers all 7 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-cocktails": {
      "url": "https://context.gnist.ai/mcp/cocktails/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`get_cocktail`

Get a specific cocktail recipe by its ID. Returns full recipe including ingredients, instructions, and metadata.

Parameter	Type	Required	Description
`cocktail_id`	string	required	Cocktail slug ID (e.g. 'margarita', 'old-fashioned').

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_cocktail", "arguments": {"cocktail_id": "'margarita'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'cocktail_id': "'margarita'"},
            'name': 'get_cocktail'}},
)
print(resp.json())

`list_cocktails`

List cocktail recipes with optional filters. Returns matching cocktails filtered by category, base spirit, or alcoholic status.

Parameter	Type	Required	Description
`category`	any	optional	Filter by category (e.g. Classic, Tiki, Sour, Highball, Martini, Shot, Mocktail).
`base_spirit`	any	optional	Filter by base spirit (e.g. Vodka, Gin, Rum, Tequila, Whiskey).
`alcoholic`	any	optional	Filter by alcoholic (true) or non-alcoholic (false).

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_cocktails", "arguments": {"category": "Classic"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'category': 'Classic'}, 'name': 'list_cocktails'}},
)
print(resp.json())

`search_cocktails`

Search for cocktail recipes by keyword. Searches across cocktail names, ingredient names, and descriptions. Case-insensitive.

Parameter	Type	Required	Description
`query`	string	required	Search keyword — matches cocktail name, ingredients, or description.
`max_results`	any	optional	Maximum number of results (default: 20, max: 100).

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_cocktails", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_cocktails'}},
)
print(resp.json())

`get_random_cocktail`

Get a random cocktail recipe. Returns a random cocktail, optionally filtered by alcoholic or non-alcoholic.

Parameter	Type	Required	Description
`alcoholic`	any	optional	Filter by alcoholic (true) or non-alcoholic (false). Omit for any.

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_random_cocktail", "arguments": {"alcoholic": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'alcoholic': 'example'},
            'name': 'get_random_cocktail'}},
)
print(resp.json())

`search_cocktails_by_ingredient`

Find cocktails containing a specific ingredient. Partial, case-insensitive match on ingredient names.

Parameter	Type	Required	Description
`ingredient`	string	required	Ingredient name to search for (e.g. 'lime', 'bourbon', 'mint').

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_cocktails_by_ingredient", "arguments": {"ingredient": "'lime'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'ingredient': "'lime'"},
            'name': 'search_cocktails_by_ingredient'}},
)
print(resp.json())

`list_base_spirits`

List all base spirits in the cocktail database. Returns the spirit names that can be used to filter cocktails.

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_base_spirits", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_base_spirits'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/cocktails/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cocktails/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_cocktails to find items, then get_cocktail to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Cocktail Recipes provide?

Curated cocktail recipe database — 60+ recipes with ingredients, instructions, and metadata. Search by name, ingredient, spirit, or category. It exposes 7 tools: get_cocktail, list_cocktails, search_cocktails, get_random_cocktail, search_cocktails_by_ingredient, list_base_spirits, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Cocktail Recipes API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with Cocktail Recipes