Marketfront AI

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 [email protected].
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.
An MCP client — e.g. Claude Desktop, VS Code with GitHub Copilot, MCP Inspector for testing, or your own integration using the MCP TypeScript SDK.

1. Mint a session JWT

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

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

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

Response:


Code
{
  "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:

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

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

POST /mcp with {method: "initialize", ...} — server returns a fresh Mcp-Session-Id in response headers.
Include Mcp-Session-Id: <id> on every subsequent request.
Optionally GET /mcp to receive server-pushed notifications as SSE.
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):


Code
{
  "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)

Code
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:


Code
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:

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.
discoverStores({ query: "pizza", limit: 5 }) — finds stores available for the confirmed fulfillment context. Returns lean store summaries with storeId and catalogSetId.
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.
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.
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.
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.
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 — 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 — partner-user linking, token refresh.

Marketfront AI Code Mode