Install Marea in your AI client in 60 seconds

The Marea MCP server runs at https://mcp.mareaalcalina.com/mcp and exposes the catalog API as 7 marea.* tools that AI clients can call directly. Install once with your developer key and the user’s AI client will route catalog calls through MCP instead of REST — gaining MCP elicitation prompts (explicit user confirmation on publish, ToS, and plan upgrades) for free.

Step 1 — Generate a developer key

Sign in at mareaalcalina.com/developers/keys and create an mk_dev_* key with at least the developer:bootstrap scope. Keep the key secret. The MCP client passes it to the Marea server on every call.

Step 2 — Add Marea to your client

Marea speaks streamable HTTP MCP at https://mcp.mareaalcalina.com/mcp. Most clients today still expect a stdio MCP server, so the install bridges the remote HTTP endpoint via mcp-remote — a small published npm shim that pipes stdio ↔ remote HTTP.

Claude Desktop
Cursor
Continue.dev

Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the marea entry:

{
  "mcpServers": {
    "marea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.mareaalcalina.com/mcp",
        "--header",
        "Authorization: Bearer mk_dev_xxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Restart Claude Desktop. The marea.* tools appear in the tool picker.

Open ~/.cursor/mcp.json (or use Settings → MCP → Add) and add:

{
  "mcpServers": {
    "marea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.mareaalcalina.com/mcp",
        "--header",
        "Authorization: Bearer mk_dev_xxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Reload the Cursor window. The Marea tools appear in the agent picker.

In your project’s ~/.continue/config.json, add Marea under experimental.modelContextProtocolServers:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.mareaalcalina.com/mcp",
            "--header",
            "Authorization: Bearer mk_dev_xxxxxxxxxxxxxxxx"
          ]
        }
      }
    ]
  }
}

Reload the Continue extension. The Marea tools appear under the MCP section of the toolbox.

Need to share access without sharing the key? Pass Authorization: Bearer <user's mk_user_*> instead of mk_dev_* to limit the install to a single user’s storefronts — marea.bootstrap_user returns 403 insufficient_scope from the REST layer (the scope developer:bootstrap is held only by mk_dev_* keys), but every other tool works.

Step 3 — Confirm the install

Ask your AI client: “List the Marea tools you have.” You should see exactly seven:

Tool	Calls	Scope required
`marea.bootstrap_user`	`POST /v1/users`	`developer:bootstrap` (dev key)
`marea.whoami`	`GET /v1/me`	any
`marea.create_storefront`	`POST /v1/storefronts`	`catalog:write` (user key)
`marea.update_storefront`	`PATCH /v1/storefronts/:storefrontId`	`catalog:write`
`marea.create_product`	`POST /v1/storefronts/:storefrontId/products`	`catalog:write`
`marea.update_product`	`PATCH /v1/storefronts/:storefrontId/products/:productId`	`catalog:write`
`marea.publish_storefront`	`POST /v1/storefronts/:storefrontId/publish`	`storefront:publish` — fires an MCP elicitation prompt before sending the request

Verification is REST-only. POST /v1/users/:userId/verify and POST /v1/users/:userId/resendVerification are deliberately not exposed as MCP tools — the agent calls them directly with the restricted mk_user_* it received from marea.bootstrap_user. The 6-digit code flow needs the user in the loop; an MCP tool round-trip would add latency without changing the UX.

Step 4 — Try it

After the restart, ask your AI client these prompts in order. Each one validates a different layer of the install.

Verify the connection

Prompt: “List the Marea tools you have available and tell me which account I’m using via marea.whoami.”What you should see: the agent enumerates the 7 tools and reports back an email, plan tier (or free if pre-paywall), rpm/rpd quota, and a key prefix.If the agent reports fewer than 7 tools or says “I don’t have Marea tools,” the install didn’t load — restart Claude Desktop fully (Cmd-Q) and try again. See Troubleshooting.

Bootstrap a test merchant (only with a dev key)

Prompt: “Bootstrap a Marea account for test+demo@example.com with display name ‘Demo Tacos’ and source agent ‘my-agent-name’.”What you should see: a verification email lands in the test inbox, and the agent reports back a userId, a userKey (the restricted mk_user_*), and a verificationExpiresAt timestamp.This step is rejected (403 insufficient_scope) if you installed with an mk_user_* key — bootstrap requires developer:bootstrap, which only dev keys carry.

Create + publish a storefront

Prompt: “Create a Marea storefront called ‘Demo Tacos’ in MXN with Mexican-Spanish settings. Add a product ‘Taco al pastor’ for 35 pesos. Then publish the storefront.”What you should see:

The agent calls marea.create_storefront, then marea.create_product, then marea.publish_storefront.
Before the publish call, your AI client pops an explicit confirmation dialog with the message “Publishing this storefront makes it publicly visible at <publicUrl>…”. This is the MCP elicitation primitive — you must accept it for publish to proceed.
If the account hasn’t accepted Marea’s terms, publish returns 451 tos_not_accepted with a nextActions[].url pointing to the dashboard ToS modal. The agent will surface that link verbatim.
If the account’s plan can’t publish (e.g. NO_ACTIVO pre-paywall), publish returns 402 plan_limit with an upgrade.upgradeUrl to the upgrade flow.

What each tool does

Tool	Trigger prompts
`marea.whoami`	”Which Marea account am I using?” / “What’s my plan and quota?”
`marea.bootstrap_user`	”Sign up Lupita at lupita@example.com for Marea.” / “Create a Marea account for this new merchant.”
`marea.create_storefront`	”Make a new digital menu for tacos.” / “Set up Lupita’s storefront.”
`marea.update_storefront`	”Rename the storefront to ‘Tacos de la Esquina’.” / “Change the currency to USD.”
`marea.create_product`	”Add a taco al pastor for 35 pesos.” / “Add these 5 menu items to the storefront.”
`marea.update_product`	”Change the price of item X to 45 pesos.” / “Hide that product.”
`marea.publish_storefront`	”Publish the storefront so customers can order.” / “Make this menu live.” — fires confirmation prompt

Common errors and what they mean

When a tool fails, the agent surfaces a structured error envelope (see Errors for the full schema). The most common ones:

You see	What happened	What to do
`auth / insufficient_scope` (403)	Your key doesn’t have the right scope for that tool. Most often: using `mk_user_*` to call `marea.bootstrap_user`.	Re-install with a dev key, or use a different tool.
`plan_limit / plan_blocks_publish` (402)	The account’s plan can’t publish (typically pre-paywall `NO_ACTIVO`).	Click `error.upgrade.upgradeUrl` — surfaces in the agent’s response — and upgrade.
`tos_not_accepted` (451)	The account owner hasn’t accepted Marea’s terms.	Open `error.nextActions[0].url` in a browser and accept.
`rate_limited` (429)	You exceeded `rpm: 60` or `rpd`.	Wait `Retry-After` seconds; the agent should back off automatically.
`not_found / storefront_not_found` (404)	The `storefrontId` doesn’t exist or isn’t owned by this account.	Confirm the id with `marea.whoami` + an existing storefront, or call `marea.create_storefront` first.

The marea.publish_storefront confirmation dialog is always shown before the REST call fires, even if the underlying account is fully eligible — publishing is destructive and user-visible by design.

Choosing dev vs user key for the install

Most readers will install with their mk_dev_* key — it unlocks all 7 tools including marea.bootstrap_user. A few cases prefer a mk_user_* instead:

Sharing a sandbox: you want the install scoped to a single account so the agent can only see that account’s storefronts. Use a mk_user_* — marea.bootstrap_user returns 403 insufficient_scope but the other 6 tools work normally.
Personal scripting: you’re a developer managing your own Marea account and don’t want to bootstrap a synthetic test user. Use a mk_user_* for your real account — issued from the dashboard’s “Personal API key” path (or via POST /v1/users/:userId/keys with your dev key + your own userId).

The same install JSON works for both — only the bearer-token prefix changes. See Two-tier keys for the full model.

Discovery

Clients that support MCP discovery can find the server via the well-known endpoint:

https://mcp.mareaalcalina.com/.well-known/mcp.json

The well-known doc is a lightweight discovery manifest — it returns the server URL, the list of the same 7 tool names, and the auth requirement (Authorization: Bearer mk_dev_* or Bearer mk_user_*). Example response:

{
  "name": "marea",
  "version": "1.0.0-alpha",
  "url": "https://mcp.mareaalcalina.com/mcp",
  "auth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "mk_dev_* | mk_user_*"
  },
  "tools": [
    "marea.whoami",
    "marea.bootstrap_user",
    "marea.create_storefront",
    "marea.update_storefront",
    "marea.create_product",
    "marea.update_product",
    "marea.publish_storefront"
  ]
}

Per-tool JSON input schemas are exposed over the MCP protocol via the tools/list call once the client connects, not in this well-known doc — that’s the canonical MCP discovery path. The well-known is for HTTP-layer crawlers that need only the server location + auth handshake.

MCP-only meta arguments

Every write tool (marea.bootstrap_user, marea.create_storefront, marea.update_storefront, marea.create_product, marea.update_product, marea.publish_storefront) accepts two optional underscore-prefixed arguments that don’t appear in the REST body:

Argument	Maps to	Purpose
`_idempotencyKey`	`Idempotency-Key` header (must be a UUID)	Deterministic retry safety — re-sending the same tool call with the same `_idempotencyKey` within 24h returns the original response. If omitted, the MCP server auto-generates one per call.
`_acceptLanguage`	`Accept-Language` header (BCP-47 tag, e.g. `es-MX`)	Localizes error messages and applied defaults. If omitted, the server defaults to `es`.

marea.publish_storefront adds a third meta argument used only when the client lacks the MCP elicitation capability:

Argument	Purpose
`_confirmed`	Set to `true` to acknowledge the destructive-publish prompt without going through MCP elicitation. Clients that support elicitation (Claude Desktop, Cursor) handle this automatically — most callers can ignore the field.

Agents that need bulletproof retries should supply _idempotencyKey themselves rather than relying on the server-side default; the auto-generated key changes on every call, so an auto-retry on a network blip would be treated as a NEW request.

Troubleshooting

“Cannot find mcp-remote” — bump to npm ≥ 7 and Node ≥ 18; npx -y will fetch on first run.
“401 missing_authorization” — the --header argument was dropped during JSON-edit (common when editors strip backslashes). Re-paste from this page exactly.
“403 insufficient_scope” on marea.bootstrap_user — your dev key lacks developer:bootstrap. Re-issue at mareaalcalina.com/developers/keys.
Claude Desktop doesn’t see the tools — restart Claude Desktop fully (Cmd-Q on macOS); a tab reload isn’t enough.

Next steps

Bootstrap a user — same flow, narrated for the REST surface (verify is REST-only in MCP too).
Add and edit products — the calls behind marea.create_product and marea.update_product.
Publish a storefront — including the 402 / 422 / 451 gates that marea.publish_storefront surfaces via MCP elicitation.

Get Started

Concepts

Webhooks

Install Marea in Claude Desktop, Cursor, and Continue.dev

Install Marea in your AI client in 60 seconds

Step 1 — Generate a developer key

Step 2 — Add Marea to your client

Step 3 — Confirm the install

Step 4 — Try it

What each tool does

Common errors and what they mean

Choosing dev vs user key for the install

Discovery

MCP-only meta arguments

Troubleshooting

Next steps

​Install Marea in your AI client in 60 seconds

​Step 1 — Generate a developer key

​Step 2 — Add Marea to your client

​Step 3 — Confirm the install

​Step 4 — Try it

​What each tool does

​Common errors and what they mean

​Choosing dev vs user key for the install

​Discovery

​MCP-only meta arguments

​Troubleshooting

​Next steps

Install Marea in your AI client in 60 seconds

Step 1 — Generate a developer key

Step 2 — Add Marea to your client

Step 3 — Confirm the install

Step 4 — Try it

What each tool does

Common errors and what they mean

Choosing dev vs user key for the install

Discovery

MCP-only meta arguments

Troubleshooting

Next steps