npm package: @potion5/mcp-server
Description: Model Context Protocol server for integrating Potion API with AI agents
Author: Potion
Latest version: 1.0.0

# 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

### Environment Variables

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

### Claude Desktop Integration

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"
      }
    }
  }
}
```

### Claude Code Integration

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

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

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

### Building

```bash
npm run build
```

### Running Locally

```bash
POTION_API_KEY=pk_sandbox_xxx npm run dev
```

### Testing

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