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

# Connect Marea to Claude, ChatGPT or your AI client

> Connect your Marea account to an AI client over MCP and manage your menu by talking to it. OAuth for merchants, static keys for developers.

# Connect Marea to your AI client

Marea runs an MCP server at `https://mcp.mareaalcalina.com/mcp`. Connect it once and your AI client manages your page for you.

**What the AI can do:** list your products and prices; add or edit products (title, description, price, sale price, category, stock, photo by URL); hide a sold-out item and bring it back; change hours, delivery, pickup and dine-in, branding and categories; create a new page and publish it when you say so.

**What it cannot do yet:** read or manage orders and customers; delete a product (hide it instead); upload a photo from your computer (a public image URL works); change the WhatsApp number that receives orders (set at creation, changed in the dashboard).

Publishing needs the same two things as in the dashboard: accepted terms and a plan that can publish. If either is missing, the AI shows you the link to fix it.

## ChatGPT

<Steps>
  <Step title="Open connectors">
    In ChatGPT settings, open Connectors (on some plans it lives under Apps or developer mode).
  </Step>

  <Step title="Add the server">
    Create a connector with this URL and choose OAuth. There is no client id or secret to paste.

    ```
    https://mcp.mareaalcalina.com/mcp
    ```
  </Step>

  <Step title="Connect">
    Sign in to Marea in the window that opens and press Autorizar.
  </Step>
</Steps>

## Claude (claude.ai, Desktop, mobile)

<Steps>
  <Step title="Open connectors">
    Settings (Ajustes), then Connectors (Conectores), then add a custom connector.
  </Step>

  <Step title="Add the server">
    Name it `Marea` and paste the same URL:

    ```
    https://mcp.mareaalcalina.com/mcp
    ```
  </Step>

  <Step title="Connect">
    Click Connect, sign in with the account that owns your page, and press Autorizar.
  </Step>
</Steps>

## Claude Code, Cursor, VS Code

Add the URL as an HTTP MCP server with no headers. The first call returns a `401` with an OAuth challenge and the client opens your browser to sign in.

```bash theme={null}
# Claude Code
claude mcp add --transport http marea https://mcp.mareaalcalina.com/mcp
```

```json theme={null}
// Cursor: ~/.cursor/mcp.json
{ "mcpServers": { "marea": { "url": "https://mcp.mareaalcalina.com/mcp" } } }
```

## Check it worked, then try these

Ask **"¿Qué cuenta de Marea tienes conectada?"**. The AI calls `marea.whoami` and answers with your email and plan. Then:

* "¿Qué productos tengo en mi menú y a qué precio?"
* "Sube el precio de los tacos al pastor a 45 pesos."
* "Oculta el flan, se nos acabó."
* "Cambia el horario del domingo a 9:00 a 17:00."
* "Agrega 'Agua de horchata' a 25 pesos en la categoría Bebidas."
* "Publica mi página." (the AI asks you to confirm; publishing is customer visible)

Hours, delivery, pickup and dine-in changes go live immediately. Design changes wait for publish.

## Developers and agents without a browser

Pass a key as a bearer header: `mk_user_*` for your own account, `mk_dev_*` only if you create Marea accounts for other people. Mint keys at [mareaalcalina.com/developers/keys](https://mareaalcalina.com/developers/keys); see [API keys](/concepts/keys).

<Tabs>
  <Tab title="Claude Desktop (config file)">
    ```json theme={null}
    {
      "mcpServers": {
        "marea": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.mareaalcalina.com/mcp",
                   "--header", "Authorization: Bearer mk_user_your_key_here"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenAI Agents SDK">
    ```python theme={null}
    from agents.mcp import MCPServerStreamableHttp

    marea = MCPServerStreamableHttp(
        name="marea",
        params={"url": "https://mcp.mareaalcalina.com/mcp",
                "headers": {"Authorization": "Bearer mk_user_your_key_here"}},
    )
    ```

    With the Anthropic Messages API, list the server under `mcp_servers` with `url` and `authorization_token`.
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl -sS https://mcp.mareaalcalina.com/mcp \
      -H "Authorization: Bearer mk_user_your_key_here" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    ```

    `401` means the key is missing or revoked. `406` means the `Accept` header was dropped.
  </Tab>
</Tabs>

## The tools

| Tool | What it does | REST call behind it | Needs |
| - | - | - | - |
| `marea.whoami` | Connected account, plan, remaining quota | `GET /v1/me` | `marea.read` |
| `marea.list_storefronts` | Your pages with id, name, slug and links | `GET /v1/storefronts` | `marea.read` |
| `marea.get_storefront` | One page in full: hours, delivery, branding, categories, published state | `GET /v1/storefronts/:id` | `marea.read` |
| `marea.list_products` | Products of one page with prices and hidden state | `GET /v1/storefronts/:id/products` | `marea.read` |
| `marea.create_storefront` | Create a page, optionally with up to 100 products | `POST /v1/storefronts` | `marea.write` |
| `marea.update_storefront` | Change hours, delivery, pickup, currency, branding, categories | `PATCH /v1/storefronts/:id` | `marea.write` |
| `marea.create_product` | Add one product | `POST /v1/storefronts/:id/products` | `marea.write` |
| `marea.update_product` | Change a product, or hide it with `hide: true` | `PATCH /v1/storefronts/:id/products/:productId` | `marea.write` |
| `marea.publish_storefront` | Take the page live | `POST /v1/storefronts/:id/publish` | `marea.publish` |
| `marea.bootstrap_user` | Create a Marea account for someone else | `POST /v1/users` | `mk_dev_*` key only |

An OAuth connection only lists the tools its scopes cover. There is no bootstrap scope: `marea.bootstrap_user` needs a developer key. Email verification stays on REST because the six digit code needs the person in the loop.

## For AI agents

* **Read first:** [`llms.txt`](https://docs.mareaalcalina.com/llms.txt) and [`AGENTS.md`](https://docs.mareaalcalina.com/AGENTS.md). Every page also serves as Markdown at `<page>.md`.
* **Tool descriptions are the spec.** Every argument is described; `businessType` and `currency` list their accepted values. Read `tools/list` once per session.
* **Ids are prefixed and opaque:** pages `stf_…`, products `prd_…`. Get them from list tools or from what a create call returns. Never construct one.
* **Start with `marea.list_storefronts`.** If there is more than one page, ask which one before writing.
* **Updates are patches, except arrays.** Omitted fields keep their value, but `categories`, `blocks` and each `schedule` day are replaced whole. To add a category, read the current list and send it complete.
* **Hide, do not delete.** `hide: true` on `marea.update_product` takes an item off the menu and keeps it.
* **Results are JSON** in `content[0].text` and, on success, `structuredContent`. REST errors return `isError: true` with the envelope (`type`, `code`, `message`, `nextActions[]`, `upgrade`) in `_meta.error`; schema failures return a plain `-32602` message naming the field. Branch on `code`; show `nextActions[]` and `upgrade.upgradeUrl` verbatim.
* **Publishing needs a person.** Confirm before calling `marea.publish_storefront`; never chain it after an edit. Expect `451` (terms) or `402` (plan) and surface the link.
* **Retries:** set `_idempotencyKey` (UUID v4) on any write you might retry; the same key within 24h returns the original result. Back off on `429` for `Retry-After` seconds. `_acceptLanguage` only affects bootstrap defaults; error messages are English.
* **Language:** merchants are Spanish-speaking (Mexico, Colombia, Costa Rica, Peru). Product names, categories and `businessType` values are Spanish.

## Disconnect

From the AI client's connector settings, or from the dashboard: each connection is a key named after the app (for example `Claude · claude.ai`) under Desarrolladores, Claves API. Delete it and the app loses access on its next call.

## Troubleshooting

* **"Couldn't reach the server":** check the URL ends in `/mcp`. `GET` answers `405`; that is expected.
* **"Authorization failed" or the consent page loops:** sign in to Marea with the account that owns the page, then retry. The consent page shows the host of the app that is asking.
* **Publish blocked:** `402` means the plan cannot publish (upgrade link in the response); `451` means the terms are not accepted (dashboard link in the response).
* **Tools disappeared:** the connection's key was deleted in the dashboard. Reconnect from the client.
* **`401` with a static key:** the header was dropped by an editor, or the key was revoked. Re-paste or mint a new key.
* **`429`:** wait `Retry-After` seconds. See [Rate limits](/concepts/rate-limits).

## Discovery and transport

Streamable HTTP, stateless, `POST` only. OAuth clients discover everything from the `WWW-Authenticate` challenge on a `401`. For clients built by hand:

| Document | URL |
| - | - |
| Protected resource metadata (RFC 9728) | `https://mcp.mareaalcalina.com/.well-known/oauth-protected-resource` (also `/mcp` path form) |
| Authorization server metadata (RFC 8414) | `https://mcp.mareaalcalina.com/.well-known/oauth-authorization-server` |
| Server manifest | `https://mcp.mareaalcalina.com/.well-known/mcp.json` |

Registration: Client ID Metadata Documents (preferred) or Dynamic Client Registration. Redirect URIs: any `https://` URI, or loopback with any port. Access tokens last 60 minutes; refresh tokens 90 days and rotate. Registry listing: `com.mareaalcalina/storefront`.

## Next steps

* [Add and edit products](/quickstart/products), the REST view of the product tools.
* [Publish a storefront](/quickstart/publish), the 402, 422 and 451 gates.
* [API keys](/concepts/keys), including the keys an AI connection creates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.