> ## Documentation Index > Fetch the complete documentation index at: https://docs.craveup.com/llms.txt > Use this file to discover all available pages before exploring further. # Use the CraveUp MCP Server > Connect AI agents to CraveUp tools for storefront setup, menu import, readiness checks, and go-live onboarding. The CraveUp MCP server is an agent-facing developer tool. It can create or update restaurant setup data when authenticated, so connect it only in workspaces where the agent is allowed to make those changes. CraveUp provides a Model Context Protocol server through the `@craveup/mcp` package. It lets AI agents use Crave-specific tools instead of guessing API shapes from memory. Use it when you want an agent to: * inspect or import menus * connect a storefront project to a Crave location * check storefront readiness before launch * configure location ordering settings * work through go-live onboarding steps * fetch Crave implementation guidance while building a storefront ## Setup The MCP server runs over stdio. Use the public npm package for normal usage outside this monorepo, or point your client at the local repo build when testing unreleased tools. You do not need a clone of `craveup-turborepo` to use the MCP server — `npx -y @craveup/mcp` fetches everything it needs. Most configurations below set `CRAVEUP_API_KEY` because menu imports, edits, and private readiness checks need a trusted server credential. Public storefront guides, project wiring, and published menu reads do not use that key. If you do not have an organization yet, register the server with no credentials and sign in from chat instead — see [Sign in from chat](#sign-in-from-chat). ### Cursor Add this to your Cursor MCP configuration: ```json theme={null} { "mcpServers": { "craveup": { "command": "npx", "args": ["-y", "@craveup/mcp"], "env": { "CRAVEUP_ENVIRONMENT": "sandbox", "CRAVEUP_API_KEY": "crv_test_...", "CRAVEUP_LOCATION_ID": "loc_..." } } } } ``` Restart Cursor or reload the window after changing the MCP configuration. Inside `craveup-turborepo`, pnpm workspace resolution can shadow the published package. If you are working in this repo, use the local repo build configuration below. ### Codex Add separate sandbox and production servers from the terminal: ```bash theme={null} codex mcp add craveup-sandbox \ --env CRAVEUP_ENVIRONMENT=sandbox \ --env CRAVEUP_API_KEY=crv_test_... \ --env CRAVEUP_LOCATION_ID=loc_... \ -- npx -y @craveup/mcp codex mcp add craveup-production \ --env CRAVEUP_ENVIRONMENT=production \ -- npx -y @craveup/mcp ``` If your Codex configuration uses TOML, add: ```toml theme={null} [mcp_servers.craveup] command = "npx" args = ["-y", "@craveup/mcp"] [mcp_servers.craveup.env] CRAVEUP_ENVIRONMENT = "sandbox" CRAVEUP_API_KEY = "crv_test_..." CRAVEUP_LOCATION_ID = "loc_..." ``` ### Claude Code CraveUp is a local stdio MCP server, not a hosted HTTP endpoint. Register separate sandbox and production processes at user scope: ```bash theme={null} claude mcp add -s user craveup-sandbox \ -e CRAVEUP_ENVIRONMENT=sandbox \ -- npx -y @craveup/mcp claude mcp add -s user craveup-production \ -e CRAVEUP_ENVIRONMENT=production \ -- npx -y @craveup/mcp ``` Run `/mcp` in Claude Code to inspect or reconnect the server. Start a new Claude Code session if the current session does not refresh its tool inventory after registration. Use `-s project` only when you intentionally want to commit a team-wide `.mcp.json`. Never place API keys or access tokens in that file. ### Claude Desktop Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "craveup": { "command": "npx", "args": ["-y", "@craveup/mcp"], "env": { "CRAVEUP_ENVIRONMENT": "sandbox", "CRAVEUP_API_KEY": "crv_test_...", "CRAVEUP_LOCATION_ID": "loc_..." } } } } ``` Restart Claude Desktop after saving the file. ### Local repo build Use this when you are working inside `craveup-turborepo` and need the newest MCP tools from source: ```bash theme={null} pnpm --filter @craveup/mcp build ``` Then configure your MCP client to run the built CLI: ```json theme={null} { "mcpServers": { "craveup": { "command": "node", "args": ["/absolute/path/to/craveup-turborepo/packages/mcp/dist/cli.js"], "env": { "CRAVEUP_ENVIRONMENT": "sandbox", "CRAVEUP_API_KEY": "crv_test_...", "CRAVEUP_LOCATION_ID": "loc_..." } } } } ``` ## Environment and authentication `CRAVEUP_ENVIRONMENT` is required and must be `sandbox` or `production`. The MCP server resolves the dashboard, public/admin APIs, Clerk issuer/client, expected API-key prefix, and credential namespace from that one value. It refuses a test/live key or endpoint mismatch before making a request. The environment is immutable for the lifetime of an MCP process. Use two named registrations rather than an in-session switch: `craveup-sandbox` for development and `craveup-production` for go-live work. This keeps hosts, credentials, API keys, and browser sessions isolated. | Environment | Dashboard | API key prefix | | ------------ | ------------------------------- | -------------- | | `sandbox` | `sandbox.dashboard.craveup.com` | `crv_test_...` | | `production` | `dashboard.craveup.com` | `crv_live_...` | Sandbox remains isolated from live data and can be used for storefront setup, catalog, and cart development. During the current direct-charge cutover, ordinary Stripe payment admission is deliberately hard locked in both sandbox and production: the API returns `STRIPE_DIRECT_CHARGE_CUTOVER_INCOMPLETE`. Present checkout as temporarily unavailable and do not retry or bypass that response. Dashboard, MCP, and setup tools remain available while the payment cutover is completed. The MCP server supports three authentication modes. | Mode | Use it for | Required setup | | ------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **Crave API key** | Menu import, product edits, integration status, and the private part of readiness checks | Set `CRAVEUP_API_KEY`, and usually `CRAVEUP_LOCATION_ID` | | **Public Storefront API** | Published menu reads, direct-integration guides, and project environment wiring | No credential; provide a published `locationId` when the tool needs one | | **CraveUp login session** | Organization setup, project wiring, go-live onboarding, and dashboard-backed operations | Ask the agent to sign you in (see below), run `craveup login`, or set `CRAVEUP_ACCESS_TOKEN` | | **Expo robot token** | Dispatch and monitor approved internal mobile release workflows | Set `EXPO_TOKEN` in the MCP server environment; never put it in prompt text | To create an API key, open Business Manager and go to [Dashboard > Developers > API Development > Step 1 - API Keys](/guides/generate-api-key). API keys are tied to an organization and may be restricted to specific locations; each MCP call still needs a target `locationId`. ### Sign in from chat Requires `@craveup/mcp` 0.5.0 or later. An API key is scoped to an organization that already exists, so it cannot unlock organization setup or the go-live tools. For those, the agent can start a browser sign-in for you — no `craveup login` in a terminal, and no API key in the configuration. `CRAVEUP_ENVIRONMENT` is still required, since it selects which dashboard and Clerk issuer the sign-in targets: ```json theme={null} { "mcpServers": { "craveup": { "command": "npx", "args": ["-y", "@craveup/mcp"], "env": { "CRAVEUP_ENVIRONMENT": "sandbox" } } } } ``` Then ask the agent to sign you in. It runs: 1. `start_crave_auth` — returns a hosted Crave Up URL. Open it and sign in, or create a free account. 2. `complete_crave_auth` — finishes the exchange and stores the session. The session is written to the macOS keychain, falling back to `~/.config/craveup/credentials.json`, and is shared with the `craveup` CLI — so signing in through either one satisfies the other. Run `whoami` at any time to confirm which account is active. On versions before 0.5.0 these tools are absent. Upgrade, or run `craveup login` from a terminal to produce the same shared session. Normal MCP requests reuse the persisted CLI/MCP session; they do not open a browser. Browser authentication happens only when `start_crave_auth` (or `craveup login`) is explicitly started. Sandbox and production sessions are stored separately. Do not put production API keys in shared prompt text, screenshots, recordings, or public repository files. Pass credentials through the MCP client environment instead. ## Available tools Exact tool availability depends on the installed package version. The current repository source exposes these tool groups; installed npm versions may differ: | Tool group | Examples | Purpose | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Onboarding** | `get_onboarding_flow`, `whoami`, `create_organization`, `connect_project` | Move a restaurant project from first setup to a connected Crave storefront | | **Browser auth** | `start_crave_auth`, `complete_crave_auth`, `cancel_crave_auth` | Sign in or sign up from chat without leaving the conversation (0.5.0 and later) | | **Menu and storefront** | `import_menu`, `list_menus`, `get_product`, `update_product`, `set_product_availability`, `delete_product`, `check_storefront_readiness` | Import, inspect, edit, and verify storefront data | | **Location settings** | `get_location_settings`, `update_store_hours`, `set_takeout_enabled`, `set_scheduled_orders_enabled`, `open_location_for_orders` | Fix ordering gates such as closed-store or unavailable pickup states | | **Discounts** | `list_discounts`, `create_order_discount` | Read location promo codes and create order-level discounts idempotently | | **Go-live** | `get_onboarding_status`, `set_location_address`, `set_fulfillment_methods`, `list_subscription_plans`, `start_subscription_checkout` | Continue setup at any time; subscription and Connect are required only for production payments | | **Guidance** | `get_integration_guide` | Ask for Crave-specific implementation guidance while coding | | **Runtime status** | `get_mcp_capabilities` | Inspect versions, policy digest, and fail-closed compatibility blockers without credentials | | **Mobile releases** | `check_mobile_release_readiness`, `start_mobile_release`, `get_mobile_release_status` | Preflight internal releases and dispatch TestFlight with explicit approval | Multi-location and sandbox tools — `create_location`, `delete_location`, `list_locations`, `get_location_orders`, `list_customers`, `set_menu_active`, and `seed_sandbox_analytics` — are available from 0.4.0. Browser auth is available from 0.5.0. The repo source can carry tools ahead of the published package; use the local repo build if you need one before its release. All current tools return one versioned operation envelope in both text and `structuredContent`. Review-required writes preview without side effects and require the exact returned intent digest for apply. Destructive, paid, and release operations require a separate confirmation phrase. Use `get_mcp_capabilities` to inspect the policy digest and current blockers. A ready intent digest does not claim that target pre-state, project registry evidence, bounded background jobs, or opaque cursor pagination exist; those capabilities remain fail-closed until their server/release contracts are published. Policies whose inventory says `idempotencyStrategy: unverified` remain blocked after preview. Today that includes `create_organization`, `create_location`, `start_subscription_checkout`, and `start_mobile_release`. Complete those actions in Business Manager or the provider workflow until the authoritative service provides a durable operation identity and response-loss reconciliation. `check_storefront_readiness` reads the published menu and the side-effect-free `GET /ordering-readiness` endpoint without creating a cart, then reads private integration status for payment configuration. The private step requires `CRAVEUP_API_KEY`. A ready payment check describes configuration only; the tool does not create a PaymentIntent, prove payment admission, or execute a test payment. While the direct-charge lock exists, checkout still returns `STRIPE_DIRECT_CHARGE_CUTOVER_INCOMPLETE`. For mobile releases, first run `craveup apps configure` in the Expo/React Native project and commit the generated `.eas/workflows` files. The MCP release trigger only supports internal TestFlight. It requires the exact confirmation phrase and a scoped Expo robot token because dispatching a workflow consumes EAS build minutes. Android internal publishing stays in the CLI so the local Play submit profile can be verified immediately before submission. Apple password/2FA prompts remain in a visible terminal, and public App Store review remains a separate App Store Connect action. ## Example prompts Once connected, ask your agent for Crave-specific work: ```text theme={null} Use the CraveUp MCP server to sign me in to Crave Up, then tell me which account and organization I am on. ``` ```text theme={null} Use the CraveUp MCP server to inspect my current location, list active menus, and tell me whether this storefront can accept orders. ``` ```text theme={null} Use the CraveUp MCP server and the Crave docs to build a Next.js menu page with category tabs, cart state, and the server-selected checkout payment-session flow. If payment admission returns STRIPE_DIRECT_CHARGE_CUTOVER_INCOMPLETE, show checkout as temporarily unavailable without retrying. ``` ```text theme={null} Import this menu into Crave. Preserve categories, products, prices, modifier groups, availability, and image URLs. After import, verify the active menu with list_menus. ``` ## Faster setup with a prebuilt prompt Use the prebuilt prompt when you want an AI agent to start with Crave Cloud, Crave.js, Storefront API, and MCP context already loaded. Copy a ready-to-use agent prompt for building a Crave-powered storefront. Create a server-only key only when private MCP tools need it. A storefront never receives that key. ## Troubleshooting | Problem | Fix | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The agent cannot see CraveUp tools | Restart the MCP client after changing configuration. In Cursor, reload the window. | | `CRAVEUP_ENVIRONMENT is required` | Set it to `sandbox` or `production` in the MCP server environment. | | `No Crave session` appears | Call `start_crave_auth` then `complete_crave_auth`, run `craveup login`, or set `CRAVEUP_ACCESS_TOKEN`. | | Storefront tools fail with an auth error | Confirm the key prefix matches the selected environment and can access the target location. | | Stripe checkout reports `STRIPE_DIRECT_CHARGE_CUTOVER_INCOMPLETE` | The direct-charge activation lock is working as designed. Keep setup/catalog/cart work available, show checkout as temporarily unavailable, and do not retry or bypass it. | | Sandbox asks for Stripe Connect setup | Do not bypass the returned setup state. During the cutover, continue non-payment work; after activation, follow the current onboarding status for that location. | | Menu tools use the wrong location | Set `CRAVEUP_LOCATION_ID`, or pass `locationId` explicitly in the tool call. | | New tools do not appear after a repo update | Rebuild `@craveup/mcp`, then restart the MCP client. |