Potion MCP Server

Model Context Protocol (MCP) server for integrating the Potion API with AI agents like Claude.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. This server exposes Potion's beverage formulation capabilities as MCP tools.

Installation

``bash
npm install @potion/mcp-server
`

Or run directly with npx:

`bash
npx @potion/mcp-server
`

Configuration

$3

`bash
POTION_API_KEY=pk_live_your_key_here # Required: Your Potion API key
POTION_API_URL=https://api.potion.com # Optional: Custom API URL
`

$3

Add to your Claude Desktop configuration (claude_desktop_config.json):

`json
{
"mcpServers": {
"potion": {
"command": "npx",
"args": ["@potion/mcp-server"],
"env": {
"POTION_API_KEY": "pk_live_your_key_here"
}
}
}
}
`

$3

Add to your Claude Code MCP settings:

`json
{
"mcpServers": {
"potion": {
"command": "npx",
"args": ["@potion/mcp-server"],
"env": {
"POTION_API_KEY": "pk_live_your_key_here"
}
}
}
}
`

Available Tools

$3

| Tool | Description |
|------|-------------|
| potion_generate_formulation | Generate an AI-powered beverage formulation |
| potion_list_formulations | List existing formulations |
| potion_get_formulation | Get details of a specific formulation |
| potion_create_variations | Generate variations of a formulation |
| potion_get_substitutions | Get ingredient substitution suggestions |

$3

| Tool | Description |
|------|-------------|
| potion_search_ingredients | Search the ingredient database |
| potion_augment_ingredient | Get AI-enhanced ingredient data |
| potion_check_compatibility | Check ingredient compatibility |

$3

| Tool | Description |
|------|-------------|
| potion_generate_sop | Generate Standard Operating Procedure |
| potion_generate_labeling | Generate FDA-compliant labeling |
| potion_check_claims | Check marketing claims eligibility |

$3

| Tool | Description |
|------|-------------|
| potion_check_compliance | Run compliance check on formulation |
| potion_get_dtc_shipping | Get DTC shipping rules by state |

$3

| Tool | Description |
|------|-------------|
| potion_search_copackers | Search for copackers |
| potion_recommend_copackers | Get AI copacker recommendations |
| potion_search_distributors | Search for distributors |

$3

| Tool | Description |
|------|-------------|
| potion_chat | Chat with the Potion AI assistant |

Example Usage

Once configured, you can ask Claude:

> "Generate a low-calorie citrus energy drink formulation with natural caffeine"

Claude will use the potion_generate_formulation tool to create the formulation.

> "Check if my formulation can be sold in California and New York"

Claude will use the potion_check_compliance tool with the appropriate states.

> "Find organic-certified copackers in California that can do hot fill"

Claude will use the potion_search_copackers tool with the specified filters.

Tool Schemas

All tools follow the MCP tool specification with JSON Schema parameters:

`typescript
{
name: "potion_generate_formulation",
description: "Generate an AI-powered beverage formulation based on natural language requirements",
inputSchema: {
type: "object",
required: ["prompt", "category", "subcategory"],
properties: {
prompt: {
type: "string",
description: "Natural language description of desired beverage"
},
category: {
type: "string",
enum: ["nonalc", "alc", "functional", "supplement"],
description: "Primary beverage category"
},
subcategory: {
type: "string",
description: "Specific subcategory (e.g., csd.energy_drink)"
},
constraints: {
type: "array",
items: { type: "string" },
description: "Formulation constraints like 'organic', 'kosher'"
}
}
}
}
`

Development

$3

`bash
npm run build
`

$3

`bash
POTION_API_KEY=pk_sandbox_xxx npm run dev
`

$3

`bash
npm test
`

Security

- API keys are passed via environment variables, never in tool arguments
- The server validates all inputs before making API calls
- Sandbox keys (pk_sandbox_*`) are recommended for development

Requirements

- Node.js 18+
- Potion API key (Enterprise plan required for live keys)

Support

- Documentation: https://potion.com/documentation
- MCP Specification: https://modelcontextprotocol.io
- Email: api-support@potion.com