# MCP Server (Pizza x402)

Pizza x402 maintains an MCP server through a dedicated private preview repo. It is not a launch blocker and is not the public-release authority for checkout behavior:

- Private preview repo for authorized maintainers: `https://github.com/pizzax402/pizzax402-mcp`
- Runtime-side implementation source in `pizzax402/pizza-x402-api`: `packages/mcp-server`

Use Direct HTTP and the OpenAPI/AGENTS contract for launch proof. Use the private preview MCP repo only when you have repository access and need an agent-host wrapper. Use the `pizza-x402-api` path when you are maintaining the canonical implementation alongside the core Pizza x402 runtime.

## Recommended Onboarding Path

- Start with `docs/public/quickstarts/first-paid-order-5-minutes.md` if you have not run a paid order yet.
- Use `docs/public/quickstarts/generic-mcp-client.md` only if you have access to the private preview MCP repo and are ready to wire the MCP server into an agent host.
- Return to this page for MCP-specific transport, auth, and compatibility details.

## Tools Exposed (Sprint 4)

Public tools:
- `get_menu`
- `create_quote`
- `confirm_order`
- `get_order_status`
- `get_wallet_setup`

Partner tools (require partner API key in MCP server config):
- `list_partner_orders`
- `ack_order`
- `fulfill_order`

The public ordering tools work without partner credentials. The partner tools are for merchant or staff operations and must stay behind `PIZZA_X402_PARTNER_API_KEY`.

## Private Preview Repo Usage (stdio)

```bash
git clone https://github.com/pizzax402/pizzax402-mcp.git
cd pizzax402-mcp
npm install
npm run dev
```

The standalone private preview repo expects a running Pizza x402 API at `http://localhost:3000` unless `PIZZA_X402_BASE_URL` says otherwise.

If you only need public ordering tools, stop here. Add `PIZZA_X402_PARTNER_API_KEY` only when you need partner operations such as `list_partner_orders`, `ack_order`, or `fulfill_order`.

## Private Preview Repo Usage (HTTP / Streamable HTTP)

Run the MCP server in HTTP mode:

```bash
cd pizzax402-mcp
PIZZA_X402_MCP_HTTP_PORT=3200 npm run dev:http
```

Default endpoint:

- `http://127.0.0.1:3200/mcp`

HTTP-mode smoke test:

```bash
npm run test:http
```

## HTTP Session Notes

- `/mcp` is a session-based MCP endpoint, not a plain REST endpoint.
- Use an MCP client SDK or host that performs the initialize handshake and persists the `Mcp-Session-Id` header.
- `GET /mcp` without `Mcp-Session-Id` returns a JSON-RPC error for the missing session header.
- `POST /mcp` without an initialize request or valid session ID returns a JSON-RPC error instead of silently creating a session.
- `GET /healthz` and `GET /metrics` are the safe raw-HTTP probes for shell-level checks.

HTTP observability endpoints (Sprint 9):

- `GET /healthz`
- `GET /metrics`

HTTP responses include:

- `X-Request-Id`

## Maintainer Path Inside `pizza-x402-api`

If you are working inside the backend runtime repo and need the source-of-truth implementation directly:

```bash
cd ../pizza-x402-api
npm run mcp:build
npm run mcp:test
npm run mcp:test:http
npx tsx packages/mcp-server/src/index.ts
npx tsx packages/mcp-server/src/index.ts --http
```

## Environment Variables

- `PIZZA_X402_BASE_URL` (default: `http://localhost:3000`)
- `PIZZA_X402_TIMEOUT_MS` (default: `10000`)
- `PIZZA_X402_PARTNER_API_KEY` (required for partner tools)
- `PIZZA_X402_MCP_HTTP_HOST` (default: `127.0.0.1`)
- `PIZZA_X402_MCP_HTTP_PORT` (default: `3200`)
- `PIZZA_X402_MCP_HTTP_PATH` (default: `/mcp`)
- `PIZZA_X402_MCP_TRANSPORT=http` (alternative to passing `--http`)

## Partner Tool Auth And Failure Modes

- Partner tools forward requests to `/partner/*` routes and require a valid `PIZZA_X402_PARTNER_API_KEY`.
- Missing or invalid partner credentials do not disable the tool definitions. Instead, partner tool calls return a structured MCP tool error with `errorCode=UNAUTHORIZED`.
- Keep public ordering and partner operations separate in your agent policy. Public ordering can be offered broadly, while partner tools should be enabled only in trusted merchant or staff contexts.

## Notes for MCP Clients

- Merchant-context parity is governed by `docs/public/merchant-context-parity-checklist.md`.
- Public MCP ordering flows should treat `merchantHandle` as the stable storefront identifier, while authenticated/operator payloads can still expose internal UUID `merchantId`.
- MCP tools should preserve merchant identity fields exactly as returned by the API rather than deriving alternate tenant labels.
- Tools with optional parameters still use object schemas. For zero-argument usage, send `arguments: {}`.
- `confirm_order` returns a structured response with `status` and `response`:
  - `status=402` for x402 payment-required branch (includes `paymentRequiredHeader` when present)
  - `status=200` for card intent or confirmed order payloads
- Use `paymentMethod` explicitly (`card` or `crypto`) to avoid ambiguous branching.
- `create_quote` surfaces Sprint 7 safety metadata (`quoteHash`, `significance`, `riskHints`, merchant identity).
- `confirm_order` accepts optional `assertions` to enforce quote hash / amount / method / currency / expiry / merchant checks before payment flow proceeds.
- Partner tools surface auth failures as structured MCP tool errors (`UNAUTHORIZED`) when `PIZZA_X402_PARTNER_API_KEY` is missing or invalid.
- HTTP mode uses MCP Streamable HTTP with session-based transports (`GET` / `POST` / `DELETE` on one endpoint).
- HTTP mode exposes basic metrics counters (`/metrics`) and emits structured JSON logs for HTTP requests/tool calls.

## Clean-Shell Smoke Checklist

1. Start the API from `pizza-x402-api`: `X402_ADAPTER=mock npm run go:run`
2. Start MCP stdio or HTTP mode from `pizzax402-mcp`
3. Probe HTTP health only with `curl http://127.0.0.1:3200/healthz` and `curl http://127.0.0.1:3200/metrics`
4. Run `npm test` or `npm run test:http` in `pizzax402-mcp`
5. If you need partner tools, rerun with `PIZZA_X402_PARTNER_API_KEY=...` set in the MCP server environment

## Compatibility and Versioning

- Compatibility matrix: `docs/public/compatibility-matrix.md`
- Merchant-context parity checklist: `docs/public/merchant-context-parity-checklist.md`
- Private preview repo bootstrap contract: `https://github.com/pizzax402/pizzax402-mcp`
- Extraction ADR: `docs/adr/ADR-0005-pizzax402-mcp-extraction-contract.md`
- MCP tool names are treated as stable once released, but the standalone repo itself remains private preview during launch.
- `pizza-x402` remains the canonical contract authority for MCP semantics during the bootstrap phase.
- Additive `structuredContent` fields are allowed; breaking changes require test/doc/changelog updates.

## Validation

- Standalone repo:
  - `npm run build`
  - `npm test`
  - `npm run test:http`
- Backend repo maintainer path:
  - `npm run mcp:build`
  - `npm run mcp:test`
  - `npm run mcp:test:http`
- Root validation still applies:
  - `npm run build`
  - `npm run check:agent-doc-drift`
  - `npm run check:skills`
  - `npm test -- --run`