> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Paste-token MCP install — 7 marea.* tools available over stdio (mcp-remote) or streamable HTTP.

# 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](https://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`](https://www.npmjs.com/package/mcp-remote) — a small published npm shim that pipes stdio ↔ remote HTTP.

<Tabs>
  <Tab title="Claude Desktop">
    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:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    Open `~/.cursor/mcp.json` (or use Settings → MCP → Add) and add:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Continue.dev">
    In your project's `~/.continue/config.json`, add Marea under `experimental.modelContextProtocolServers`:

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

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

<Steps>
  <Step title="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](#troubleshooting).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](mailto: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](/concepts/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](/concepts/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:

```json theme={null}
{
  "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](https://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](/quickstart/bootstrap) — same flow, narrated for the REST surface (verify is REST-only in MCP too).
* [Add and edit products](/quickstart/products) — the calls behind `marea.create_product` and `marea.update_product`.
* [Publish a storefront](/quickstart/publish) — including the 402 / 422 / 451 gates that `marea.publish_storefront` surfaces via MCP elicitation.