CraveUp MCP Server

A Model Context Protocol (MCP) server that lets AI agents onboard restaurant brands and manage Crave menus, storefronts, and mobile releases — entirely from natural language in chat

Quick Start | Available Tools | Authentication | Documentation

Overview

This MCP server provides Crave platform integration for Claude Code, Cursor, and other MCP-compatible clients. It covers the full merchant lifecycle: creating an organization, wiring a repo, importing menus, configuring locations, going live with subscriptions and payments, managing discounts, and dispatching guarded Expo/EAS mobile releases.

Key Features

• 34 Tools in 8 Categories — onboarding, go-live, location settings, menus, discounts, readiness checks, mobile releases, sandbox data

• Natural-Language Onboarding — "hook up this repo for Demo Bistro" → login → create org → wire .env → import menu → run iOS

• Idempotent Writes — menu imports, discount creation, and sandbox seeding are safe to re-run

• Guarded Mobile Releases — internal TestFlight only; paid EAS work requires a scoped Expo token plus explicit confirmation, and public App Store release remains human-controlled

• TypeScript — full type safety with Zod validation

• Tested — Vitest suite (53 tests) covering tools, clients, config, and readiness logic

Note: this is a local MCP server. It runs as a stdio subprocess on the developer's machine and authenticates to Crave with either your craveup login CLI session or a merchant API key. See Authentication.

After rebuilding packages/mcp/dist, restart the MCP server in your client (or reload the window) so new tools appear.

Related MCP server: agent-storefront

Quick Start

Installation

# From npm (published package)
npx -y @craveup/mcp

# Or from the monorepo
pnpm --filter @craveup/mcp build   # compiles to dist/

Configuration

Option A — Full NL onboarding (recommended for new brands). Run craveup login once in a terminal, then register the MCP server without an API key:

{
  "mcpServers": {
    "craveup": {
      "command": "node",
      "args": ["/path/to/craveup-turborepo/packages/mcp/dist/cli.js"]
    }
  }
}

The server reads your CLI session from the macOS keychain (or ~/.config/craveup/credentials.json). Alternatively set CRAVEUP_ACCESS_TOKEN in the MCP env.

Option B — Menu-only (existing location + API key). Create a merchant API key in Crave Business Manager → Settings → Developer → API Keys:

{
  "mcpServers": {
    "craveup": {
      "command": "npx",
      "args": ["-y", "@craveup/mcp"],
      "env": {
        "CRAVEUP_API_KEY": "crv_test_…",
        "CRAVEUP_LOCATION_ID": "<default location id>",
        "CRAVEUP_BASE_URL": "https://api.craveup.com"
      }
    }
  }
}

CRAVEUP_LOCATION_ID and CRAVEUP_BASE_URL are optional; every menu tool also accepts an explicit locationId.

Mobile releases. To dispatch mobile release workflows, also set a scoped Expo robot-user token in the MCP env:

{
  "env": {
    "EXPO_TOKEN": "<scoped Expo robot-user token>"
  }
}

Example chat flow

"This demo-bistro repo — hook it up to Crave for Demo Bistro. Login if you need to, create the org, import the menu, and run it on the iOS simulator."

Agent sequence:

1. whoami — confirm session (or ask user to run craveup login)

2. create_organization({ name: "Demo Bistro", mintApiKey: true })

3. connect_project({ projectPath: "…/demo-bistro", apiKey, locationId })

4. import_menu(…) from e2e/demo-menu.json

5. check_storefront_readiness — menu + ordering + payments

6. If not ready → open_location_for_orders and/or craveup integrations add stripe

7. Re-run readiness until ready: true

8. npx expo start --ios

Available Tools

Entities

CRUD-style operations are available for the following entity types:

¹ Products are created in bulk via import_menu. ² start_subscription_checkout opens a Stripe Checkout session; plans themselves are read-only. ³ start_mobile_release dispatches an EAS workflow run; deletion/cancellation stays in EAS.

Checks & Guides

Tool Reference

Run craveup apps configure in the Expo/React Native project and commit the generated workflows before using these tools. EAS builds consume plan minutes.

start_mobile_release cannot publish publicly. iOS always goes to internal TestFlight first; public App Store review remains an explicit App Store Connect action. Use craveup apps publish play-internal for Android; the CLI blocks submission unless the local EAS submit profile targets Google Play's internal track.

Authentication

This server authenticates to Crave with a merchant API key (menu, discount, and readiness tools), a CLI session from craveup login (onboarding, go-live, and location-settings tools), and optionally an Expo token (mobile release tools). No OAuth app registration or redirect URIs are needed — keys are minted directly in Crave Business Manager.

Important: Test vs Live

The server validates the prefix at startup — anything not starting with crv_ is rejected before a single request is made. Point CRAVEUP_BASE_URL at a local API (e.g. http://localhost:8000) to develop fully offline from production.

Test Setup (recommended for first run)

1. Sign in to Crave Business Manager → Settings → Developer → API Keys

2. Create a key for the location you want to work with — copy the crv_test_… value

3. Set CRAVEUP_API_KEY (and optionally CRAVEUP_LOCATION_ID) in the MCP server env

4. For session-authenticated tools (onboarding, go-live, location settings), run craveup login once in a terminal — the server reads the session from the macOS keychain or ~/.config/craveup/credentials.json

Live Setup

1. Complete the go-live checklist — get_onboarding_status shows the six steps and what's missing

2. Verify payments with check_storefront_readiness — it gates on menu, ordering session, and Stripe chargesEnabled

3. Mint a crv_live_… key in Business Manager and swap it into the MCP env

Once you have credentials

CRAVEUP_API_KEY=crv_test_…            # merchant API key (test or live)
CRAVEUP_LOCATION_ID=<location id>     # optional default; every tool also accepts locationId
CRAVEUP_BASE_URL=https://api.craveup.com   # optional; defaults to production API

CRAVEUP_ACCESS_TOKEN=<session token>  # optional alternative to the keychain session
EXPO_TOKEN=<scoped robot-user token>  # only for mobile release tools

Credential safety

Do not paste Apple passwords, 2FA codes, App Store Connect keys, or Google service-account JSON into chat. Bootstrap interactive credentials in a visible terminal; EAS stores the reusable submission credentials. EXPO_TOKEN must be a scoped Expo robot-user token, never a personal account token.

Common pitfalls

• New tools not appearing. After rebuilding packages/mcp/dist, restart the MCP server in your client (or reload the window) — clients cache the tool list per process.

• Keys are location-scoped. The API rejects requests for locations the key cannot access; use the key minted for the location you're targeting, or pass an explicit locationId.

• Session tools failing while key tools work. The two auth modes are independent — a valid CRAVEUP_API_KEY does not log you in. Run craveup login in a terminal (the MCP process cannot open a browser).

• "Restaurant is closed. Scheduled orders are not allowed." Not an auth problem: run open_location_for_orders({ locationId }) for the one-shot fix, then retry.

• Sandbox seeding refuses to run. seed_sandbox_analytics is guarded by design: it requires CRAVEUP_SANDBOX_MODE=true and a non-production CRAVEUP_ADMIN_BASE_URL — there is no override for production.

Development

Building

pnpm --filter @craveup/mcp build   # compile to dist/

Testing

pnpm --filter @craveup/mcp test    # vitest — 53 tests across 5 files

Project Structure

src/
├── clients/         # Crave + Expo/EAS API clients
├── tools/           # MCP tool definitions (7 categories)
├── handlers/        # Business logic (readiness, onboarding, guides)
├── helpers/         # Zod schemas, session, env config
├── cli.ts           # stdio entry point (craveup-mcp bin)
└── index.ts         # Server assembly + tool registration

tests/
└── unit/            # Vitest suites (53 tests)

docs/
├── ARCHITECTURE.md  # Layers, auth modes & design decisions
└── TESTING.md       # Testing patterns & conventions

Documentation

Error Handling

Tools return structured MCP error results (isError: true) rather than throwing: missing or invalid auth reports which credential is needed (session vs API key vs EXPO_TOKEN), and the API rejects keys that cannot access the requested location. Paid EAS dispatch requires an exact confirmation phrase, location deletion is a recoverable soft-archive, and sandbox seeding refuses to run unless all dev-environment guards are set.

Contributing

Note: development happens in the private CraveUp monorepo; the public craveup/craveup-mcp repo is a read-only mirror synced automatically from packages/mcp. Bug reports and feature requests are welcome as issues on the mirror; direct pushes and PRs there will be overwritten by the next sync.

Tool naming convention

• get_* / list_* / check_* — read-only

• create_* / update_* / set_* / delete_* — writes, idempotent where possible

• start_* — kicks off an external process (checkout, EAS workflow) and returns a handle

Add tests in tests/unit/ for every new tool; pnpm --filter @craveup/mcp test must pass before publishing (prepublishOnly runs build + tests).

License

MIT — see LICENSE.