Quickstart

docker run -p 4000:4000 -v $(pwd)/db:/db -d hhaluk/mocktail:3.1.6

docker-compose up -d

docker-compose up -d --build

Features

• Create Mock APIs - Support for GET/POST/PUT/PATCH/DELETE methods
• Custom Status Codes - Return any HTTP status (200, 404, 500, etc.) to test error handling
• Response Delays - Add 0-30000ms delay to simulate network latency and loading states
• JSON Editor - CodeMirror-powered editor with syntax highlighting, error detection, and code folding
• Code Examples - Instantly generate cURL, Node.js, Python, and Go code snippets for any endpoint
• Randomize & Anonymize ⚠️ Beta - Generate realistic fake data with 20+ faker types plus Custom (fixed value) and AI Generate (prompt-based) modes, with per-field configuration, live preview, and "apply same value to all" support
• Irregular Array Support - Handles arrays with inconsistent object structures, showing field frequency and applying configs selectively
• Modern Dashboard - Clean, intuitive interface built with React and Chakra UI v3
• Catalog View - Browse, search, and manage all your mock endpoints with quick actions and persistent selection
• Quick Edit - Update status codes and delays instantly via gear icon in catalog
• Test Endpoints - Test mocks directly from the catalog list with visual feedback
• Import/Export - Export mocks to JSON and import them anywhere
• Persistent Storage - SQLite database with volume mounting
• Multi-Platform - Native support for amd64 and arm64 (Intel, Apple Silicon, Raspberry Pi)
• Health Check - /health endpoint for monitoring and orchestration
• Customizable URLs - Override display URLs for reverse proxy/custom domain setups

MCP Server (AI Integration)

Mocktail includes an MCP (Model Context Protocol) server that lets AI assistants like Claude manage your mock endpoints through natural language. Available on npm as mocktail-mcp.

Examples: "List all my mocks", "Create a GET /api/users mock returning a list of users", "Import mock endpoints for a blog API."

Available Tools

Setup

claude mcp add mocktail \
  -e MOCKTAIL_URL=http://localhost:4000 \
  -e MOCKTAIL_API_KEY=your-api-key \
  -- npx mocktail-mcp

{
  "mcpServers": {
    "mocktail": {
      "command": "npx",
      "args": ["mocktail-mcp"],
      "env": {
        "MOCKTAIL_URL": "http://localhost:4000",
        "MOCKTAIL_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add mocktail \
  -e MOCKTAIL_URL=http://localhost:4000 \
  -e MOCKTAIL_API_KEY=your-api-key \
  -- node /path/to/mocktail/mcp-server/index.js

{
  "mcpServers": {
    "mocktail": {
      "command": "node",
      "args": ["/path/to/mocktail/mcp-server/index.js"],
      "env": {
        "MOCKTAIL_URL": "http://localhost:4000",
        "MOCKTAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables:

Note: If you configured MOCKTAIL_BASE_URL for a custom domain or reverse proxy, use that same URL for MOCKTAIL_URL (e.g. https://api.mycompany.com/mocktail becomes MOCKTAIL_URL=https://api.mycompany.com).

See mcp-server/README.md for more details.

Configuration

Environment Variables

MOCKTAIL_BASE_URL (optional)

Override the Mocktail URL displayed in the dashboard. Useful when deploying behind a reverse proxy or custom domain.

Note: The legacy REACT_APP_MOCKTAIL_URL environment variable is still supported for backwards compatibility.

# Example: Custom domain
MOCKTAIL_BASE_URL=https://api.mycompany.com/mocktail

# Example: Reverse proxy
MOCKTAIL_BASE_URL=https://gateway.example.com/mocktail

If not set, defaults to:

• Development: http://localhost:4000/mocktail
• Production: [your-domain]/mocktail

CORS Configuration (optional)

Configure Cross-Origin Resource Sharing (CORS) policies for the mock API.

# Allowed origins (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000

# Allowed HTTP methods (comma-separated)
# Default: GET,POST,PUT,PATCH,DELETE,OPTIONS
MOCKTAIL_CORS_METHODS=GET,POST,PUT,DELETE

# Allowed headers (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_HEADERS=Content-Type,Authorization,X-API-Key

# Allow credentials (cookies, auth headers)
# Default: false
MOCKTAIL_CORS_CREDENTIALS=true

Docker Example:

docker run -p 4000:4000 \
  -e MOCKTAIL_CORS_ORIGINS=https://myapp.com \
  -e MOCKTAIL_CORS_CREDENTIALS=true \
  hhaluk/mocktail:latest

Docker Compose Example:

services:
  mocktail:
    image: hhaluk/mocktail:latest
    ports:
      - "4000:4000"
    environment:
      MOCKTAIL_CORS_ORIGINS: "https://myapp.com,http://localhost:3000"
      MOCKTAIL_CORS_CREDENTIALS: "true"
    volumes:
      - ./db:/db

⚠️ Important Security Rule:

DO NOT combine wildcard origins with credentials:

# ❌ INVALID - Browsers will reject this combination
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=true

# ✅ VALID - Use specific origins with credentials
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000
MOCKTAIL_CORS_CREDENTIALS=true

# ✅ VALID - Use wildcard without credentials (default)
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=false

When MOCKTAIL_CORS_CREDENTIALS=true, you must specify exact origins (no * wildcard).

MOCKTAIL_API_KEY (optional)

Protect mock endpoints with API key authentication. When set, all requests to /mocktail/* must include the API key.

# Set API key
MOCKTAIL_API_KEY=your-secret-key-here

Usage:

Clients must provide the key via header or query parameter:

# Via header (recommended)
curl http://localhost:4000/mocktail/users \
  -H "X-API-Key: your-secret-key-here"

# Via query parameter
curl http://localhost:4000/mocktail/users?api_key=your-secret-key-here

What's Protected:

• 🔒 Mock endpoints (/mocktail/*) - Requires API key
• ✅ Dashboard (/) - No auth needed
• ✅ Core API (/core/v1/*) - No auth needed (dashboard uses this)
• ✅ Health check (/health) - No auth needed

Security Note: If not set, mock endpoints are open (no authentication). This is fine for local development or private networks.

Recent Changes

See the full Changelog for all release notes.

v3.1.6 — Backend & MCP endpoint leading-slash normalization (fixes /mocktail//posts/1-style double-slash URLs)

v3.1.5 — MCP endpoint path normalization (fixes double slashes), catalog pagination

v3.1.4 — MCP Server AI integration (npx mocktail-mcp), Randomize & Anonymize UX overhaul (three-column layout, Custom & AI Generate types)

v3.1.3 — Backend Logs tab with real-time monitoring, enhanced code examples with API key support, critical Go string mutation bugfix

v3.1.2 — API key authentication, configurable CORS, .env file support

v3.1.1 — Cross-reference detection, review modal, Randomize & Anonymize improvements

v3.0 Changes

🎉 What's New

• Custom Status Codes & Delays - Configure HTTP status codes and response delays per endpoint
• CodeMirror JSON Editor - Professional code editor with syntax highlighting and error detection
• Quick Actions - Test, edit, copy, and delete directly from the catalog list with icon buttons
• Chakra UI v3 - Complete UI library upgrade with modern components
• Go 1.24 & GORM v2 - Latest backend stack with improved performance
• Fiber v2.52 - Updated web framework with security patches
• Cleaner Architecture - Improved code organization and consistency
• Health Endpoint - /health for Docker health checks and monitoring
• Auto-Setup - Database directory auto-creates on first run
• Import/Export UI - Moved to Catalog tab with better UX

🔄 What Changed

• Import Tab Removed - Import functionality now in Catalog tab
• Drag & Drop Removed - Simplified to native file input
• react-dropzone Removed - Reduced dependencies

⚠️ Breaking Changes

v3.0 is not backwards compatible with v2.x databases.

However, you can migrate your data:

1. In v2, export your mocks to JSON (Catalog → Export)
2. Install v3.0
3. Import the JSON file (Catalog → Import)

Your mock endpoints will work unchanged - only the internal database structure changed.

Development

# Run backend dev server
make dev-api

# Run dashboard dev server (in another terminal)
make dev-dashboard

# Build everything
make build

# Build Docker image
make build-docker

cd mocktail-api
go run main.go

cd mocktail-dashboard
yarn install
yarn start

References

• Changelog