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

# Overview

> The 20-tool contract: scopes, strictness, freshness, ownership, and the rules every client must follow.

The complete contract for Phantom's MCP tool surface — every tool, its inputs, outputs, and behavior rules. For credentials, authentication, rate limits, and the canonical order flow, start with [Agent Onboarding](/guides/agent-onboarding).

MCP is intentionally a thin wrapper over Phantom's REST API. It introduces no separate ordering logic — every tool reuses the same service methods, scope checks, and rule validation the REST routes use.

Endpoint: `POST https://phantom.mealops.ai/mcp` (Streamable HTTP), authenticated with `Authorization: Bearer <agent-api-key>`.

## Tool list

The MCP server registers **20 tools**. The list is scope-filtered per credential: tools your key lacks the scope for are not registered at all (a discovery-only key sees 7 tools, \~3k tokens of definitions, instead of 20 at \~11k). The filter mirrors call-time enforcement exactly, including the `orders:submit` → `payments:start` implication. Calling a tool your key can't see returns the MCP "tool not found" error — if a tool seems missing, check your key's scopes. Scope upgrades apply on the next request, no reconnect needed.

| #  | Tool                          | Scope              |
| -- | ----------------------------- | ------------------ |
| 1  | `search_restaurants`          | `restaurants:read` |
| 2  | `search_menu_items`           | `menus:read`       |
| 3  | `get_availability_calendar`   | `restaurants:read` |
| 4  | `list_brand_locations`        | `restaurants:read` |
| 5  | `get_menu`                    | `menus:read`       |
| 6  | `get_restaurant_detail`       | `restaurants:read` |
| 7  | `check_delivery_availability` | `restaurants:read` |
| 8  | `validate_order`              | `orders:validate`  |
| 9  | `quote_order`                 | `orders:quote`     |
| 10 | `start_payment`               | `payments:start`   |
| 11 | `charge_payment`              | `payments:start`   |
| 12 | `charge_saved_card`           | `payments:start`   |
| 13 | `create_payout`               | `orders:submit`    |
| 14 | `void_payment`                | `payments:start`   |
| 15 | `get_payment_status`          | `payments:start`   |
| 16 | `submit_order`                | `orders:submit`    |
| 17 | `get_order_status`            | `orders:status`    |
| 18 | `get_order_tracking`          | `orders:status`    |
| 19 | `cancel_order`                | `orders:submit`    |
| 20 | `update_order`                | `orders:submit`    |

All output schemas are strict (`additionalProperties: false`): a field not declared in a tool's output schema is never passed through.

Freshness guarantees: agent listings always reflect the latest writes (concurrent duplicate searches share one computation, but results are never served from a stale cache). Menus read by `search_menu_items` may be up to 30 seconds stale, and every menu write invalidates that cache immediately. `get_menu`, validation, and quoting are never cached — they see availability flips instantly.

Order tools (`get_order_status`, `get_order_tracking`, `cancel_order`, `update_order`) enforce **ownership**: an agent may only touch orders it created. Foreign and missing orders both return `Order <id> not found.`, so order ids are not enumerable across agents.

## Canonical behavior rules

* MCP responses mirror the REST payloads as closely as possible; authorization always stays server-side.
* Payment runs after quote and before submit when the restaurant requires prepaid checkout.
* All POS providers stay behind the same tool contract — clients never see provider-specific ordering logic.
* Prefer server-resolved values (`resolvedMinLeadTimeMinutes`, `earliest_orderable_time`, the quote total, `check_delivery_availability`) over recomputing them; fall back to components only for compatibility with an older Phantom.

## Known gaps

* **Delivery transit is a flat 25 minutes** for every restaurant; a per-restaurant estimate is a known open item.