# WalletMCPPass — full reference

> MCP server for generating and signing Apple Wallet passes. This file is the detailed
> companion to /llms.txt, meant for an agent that has already decided to connect.

## Connecting

Add a remote MCP server pointing at the streamable-HTTP endpoint:

```json
{
  "mcpServers": {
    "walletmcppass": {
      "url": "https://walletmcppass.com/mcp"
    }
  }
}
```

No authentication is required during the open-beta period. The server enforces a rate limit
(30 requests/day per caller IP, 500/day global) before doing any signing work; exceeding it
returns a tool error rather than a silent failure.

## Tool: create_wallet_pass

Builds a `pass.json` for the requested style, generates a manifest, signs it with the
server's Apple Wallet Pass Type ID certificate, and returns a downloadable `.pkpass` file.

Supported `style` values: `boardingPass`, `eventTicket`, `coupon`, `storeCard`, `generic`.

Parameters (exact schema is authoritative in the GitHub repo's `server.py` —
this file is a summary, not a contract):
- `style` (string, required): one of the five styles above.
- `organization_name`, `description` (strings, required): issuer name and Wallet's
  required accessibility description.
- `logo_text` (optional): text shown next to the logo image.
- `transit_type` (optional, boardingPass only): `"Air"` (default), `"Boat"`, `"Bus"`,
  `"Generic"`, or `"Train"`.
- `barcode_message`, `barcode_format` (optional): raw barcode contents and one of
  `"QR"` (default), `"PDF417"`, `"Aztec"`, `"Code128"`. Omit `barcode_message` for no barcode.
- `background_color`, `foreground_color`, `label_color` (optional hex colors, e.g. `"#1a1a19"`).
- `relevant_date`, `expiration_date` (optional ISO 8601 timestamps); `voided` (bool, stamps VOID).
- `primary_fields`, `secondary_fields`, `auxiliary_fields`, `header_fields`, `back_fields`
  (optional lists of `{key?, label?, value}`): the pass's displayed field rows.
- `serial_number` (optional): auto-generated UUID if omitted.
- `icon_color`, `icon_text`, `logo_color` (optional): control the auto-generated icon/logo
  art (a colored square/wordmark) when `icon_png_b64`/`logo_png_b64` aren't supplied.
- `icon_png_b64`, `logo_png_b64` (optional, base64 PNG): use your own art instead.

Returns `{ download_url, expires_in_seconds, serial_number, pass_type_identifier }`.
The download link is valid for one hour.

## Source of truth

The tool's live docstring (what your MCP client actually sees) is defined in
`server.py` in https://github.com/arshwaraich/wallet-mcp — read that before relying on
exact field names, since this file may lag behind schema changes.

## Status and roadmap

- Open beta, free, no API key, IP-based rate limiting only.
- Usage-based billing (Stripe metered pricing) is planned; existing integrations will not
  need to change how they call the tool when it lands, only how they authenticate.
- Self-hosting: the full source, including the pass-signing pipeline, is public and
  documented in the repository README.