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

npm install @potion/mcp-server

Or run directly with npx:

npx @potion/mcp-server

Configuration

Environment Variables

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

Claude Desktop Integration

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

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

Claude Code Integration

Add to your Claude Code MCP settings:

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

Available Tools

Formulations

| 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 |

Ingredients

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

SOP & Labeling

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

Compliance

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

Supply Chain

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

Assistant

| 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:

{
  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

Building

npm run build

Running Locally

POTION_API_KEY=pk_sandbox_xxx npm run dev

Testing

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: [email protected]