# Ordering MCP Quickstart

Connect any MCP-compatible AI client to Gett's ordering backend in three steps.

## What you'll need

- A **partner API key** — request one from [partnerships@gett-tech.com](mailto:partnerships@gett-tech.com).
- A **user id** — the end user's Gett account you want the agent to order on behalf of. Partner-user linking is covered in [Authentication](../shared-guides/authentication).
- An **MCP client** — e.g. [Claude Desktop](https://claude.ai/download), VS Code with GitHub Copilot, [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing, or your own integration using the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).

## 1. Mint a session JWT

The MCP authenticates each connection with a Marketfront session JWT you mint via the standard session API:

```http
POST https://api.gett-tech.com/v1/marketfront/session/create
Authorization: Bearer <PARTNER_API_KEY>
Content-Type: application/json

{
  "userId": "<END_USER_ID>",
  "expirationSeconds": 604800
}
```

Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2026-04-27T12:00:00Z"
}
```

This example requests a 7-day token (`expirationSeconds: 604800`); omit the field for the 30-day default. It is scoped to **one user + one partner**. Mint a fresh one per user session.

## 2. Point your client at the MCP

The MCP speaks **Streamable HTTP** (MCP spec 2025-11-25). Endpoint:

```
https://api.gett-tech.com/mcp
```

Pass the token in `Authorization: Bearer <token>`. The client will:

1. `POST /mcp` with `{method: "initialize", ...}` — server returns a fresh `Mcp-Session-Id` in response headers.
2. Include `Mcp-Session-Id: <id>` on every subsequent request.
3. Optionally `GET /mcp` to receive server-pushed notifications as SSE.
4. `DELETE /mcp` to close the session (otherwise idle for 30 days).

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "gett-ordering": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.gett-tech.com/mcp",
        "--header",
        "Authorization:Bearer ${GETT_JWT}"
      ],
      "env": { "GETT_JWT": "<paste token from step 1>" }
    }
  }
}
```

Restart Claude Desktop; Gett Ordering will appear in the tools menu.

### MCP Inspector (fastest for testing)

```bash
npx @modelcontextprotocol/inspector
```

Transport: **Streamable HTTP**. URL: `https://api.gett-tech.com/mcp`. Custom header: `Authorization: Bearer <token>`. Click **Connect**.

### Roll-your-own client

Using the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk):

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://api.gett-tech.com/mcp"), {
    requestInit: {
      headers: { Authorization: `Bearer ${jwt}` },
    },
  })
);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));
```

## 3. Drive a flow

A minimal ordering sequence:

1. `confirmFulfillment()` — shows the address on file and elicits pickup vs. delivery. On elicitation-capable clients (Claude Desktop, Claude Web) the user is prompted via an inline form; on others the tool returns `awaitingMode: true` and `agentGuidance` telling the model to ask in chat and re-call with `mode: "delivery"` or `mode: "pickup"`. Always the first step; clears any existing cart.
2. `discoverStores({ query: "pizza", limit: 5 })` — finds stores available for the confirmed fulfillment context. Returns lean store summaries with `storeId` and `catalogSetId`.
3. `browseMenu({ catalogSetId: "<from step 2>" })` — fetches the full catalog. Use `searchMenu({ catalogSetId, query: "margherita" })` for lightweight "do you have X?" lookups without loading the whole menu.
4. `addToCart({ storeId, catalogSetId, itemId, quantity: 1 })` — the cart lives **server-side in the MCP session**. First `addToCart` pins the store; subsequent calls inherit it. Items with required modifier groups must go through `getItemOptions` first — the tool enforces this and returns `missingGroups` if you skip it.
5. `reviewOrder({ tip, deliveryInstructions })` — hits the commerce partner to compute authoritative totals (subtotal, fees, taxes, tip). Returns `amounts` + any validation `errors[]`. MCP Apps–capable clients render the `reviewOrder` widget at this step. Must complete without errors before `confirmPayment`.
6. `confirmPayment()` — shows the saved payment-on-file and asks the user to confirm placement. On elicitation-capable clients the confirmation prompt is shown inline; on others pass `confirm: true` after surfacing the total in chat. Unlocks `placeOrder`.
7. `placeOrder({ idempotencyKey })` — destructive. Charges the saved payment method. `idempotencyKey` (a UUID you mint) is required; retries with the same key collapse server-side to prevent double-charges. Carries `destructiveHint: true`.

## Error handling

All tools return structured errors under `structuredContent.errorCode` plus human-readable text. Common codes:

| Code | Meaning |
|---|---|
| `fulfillment_not_set` | Call `confirmFulfillment` first before any discovery, cart, or checkout tool. |
| `empty_cart` | Cart is empty — add items before `reviewOrder` or `placeOrder`. |
| `order_not_reviewed` | Call `reviewOrder` before `confirmPayment` — totals are computed at review time. |
| `payment_not_confirmed` | Call `confirmPayment` before `placeOrder`. |
| `no_saved_address` | User has no saved address on file. Direct them to gett.co to add one. |
| `no_saved_payment` | User has no saved payment method. Direct them to gett.co to add a card. |
| `marketfront_error` | Upstream Marketfront returned non-2xx. `structuredContent.problemDetail` has the RFC 9457 payload. |
| `unauthorized` | Bearer token missing, malformed, or expired. Mint a fresh one. |

## What's next

- [Code Mode](./code-mode) — let the model write a single JS function that composes multiple tools, cutting context cost dramatically.
- [Marketfront AI overview](./) — full tool list grouped by workflow stage.
- [Authentication deep dive](../shared-guides/authentication) — partner-user linking, token refresh.