Connect an AI assistant

Endpoint

Authentication

Every request carries a bearer token:

Authorization: Bearer …

Two ways to get one. Assistants that support OAuth (claude.ai, ChatGPT, Muse) use the sign-in flow and never see a key; anything that lets the user paste a token (Claude Code, MCP Inspector, scripts) can use a connector key.

OAuth 2.1 with PKCE (recommended)

Standard MCP authorization. The client discovers the server through /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server, registers itself dynamically, and sends the user to /oauth/authorize. Nothing to configure by hand.

How the user approves. The couple's identity lives in the app (Sign in with Apple), so the authorization page does not ask for a password. It shows an 8-character code and asks the user to open Wedding Harmony › Settings › AI Assistants › Approve a connection and type it (or tap the Open in Harmony button on the same phone). Once approved, the page redirects back to the client with the authorization code. The code on the page is valid for 10 minutes; the authorization code for 5.

Every approved connection appears in the app's key list under the assistant's registered client_name, and the couple can revoke it there at any time.

Connector keys

A connector key starts with wh_ and is created by the couple in the app under Settings › AI Assistants › Create key. It is shown exactly once; the server stores only its SHA-256 hash. Keys never expire until revoked.

• Keys belong to a person, not to a wedding. A key opens exactly the weddings that person owns or collaborates on — normally one.
• Creating a key or approving a connection requires a signed-in account (Sign in with Apple). Anonymous accounts are asked to sign in first.
• Up to 10 live keys per account. One key per assistant is the recommended pattern.
• Keys and approvals are currently done on iOS; Android is planned.

Firebase ID tokens

For testing, a Firebase Authentication ID token for the same project is accepted in place of a key. It expires after an hour and is meant for developers working on the apps, not for connectors.

A missing, unknown, expired or revoked token gets 401 with WWW-Authenticate: Bearer … resource_metadata="…", which is what starts the OAuth flow in a compliant client.

Quick start

Assistants with a "custom connector" or "MCP server" setting only need the URL; OAuth-capable ones will take the user through the approval page on their own. With a connector key, from a terminal:

MCP=https://www.weddingharmonyapp.com/mcp
KEY=wh_your_key_here

# 1. Handshake
curl -s -X POST $MCP \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'

# 2. What can it do?
curl -s -X POST $MCP \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Ask about the wedding
curl -s -X POST $MCP \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"get_wedding_overview","arguments":{}}}'

Every tool result carries a human-readable content[0].text and a machine-readable structuredContent object with the same facts:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text",
      "text": "Anna & Tom are getting married in 120 days (2027-01-19) at Schloss Hof.\nGuests: 2 of 6 people attending (4 guest records).\nTasks: 2 open, 1 done.\nBudget: 10,000 EUR planned/spent of 25,000 EUR; 15,000 EUR left." }],
    "structuredContent": {
      "partnerNames": ["Anna", "Tom"], "date": "2027-01-19", "daysUntil": 120,
      "venueName": "Schloss Hof", "currencyCode": "EUR",
      "guests": { "records": 4, "people": 6, "attendingPeople": 2 },
      "tasks": { "open": 2, "completed": 1 },
      "budget": { "total": 25000, "spent": 10000, "remaining": 15000 }
    }
  }
}

Notifications (messages without an id) are acknowledged with 202 and no body. A JSON array of messages is answered with an array.

Tools

Every tool except list_weddings accepts an optional weddingId. Leave it out to use the couple's active wedding. Money is in the wedding's currencyCode; dates are ISO 8601. Headcounts count people: a guest record, its unnamed plus-one and its children.

Read

Write

* required. Enum values (RSVP statuses, categories, priorities, vendor statuses, music moments) are listed in each tool's inputSchema from tools/list. Write tools carry MCP annotations (readOnlyHint: false, destructiveHint: false); nothing here deletes data.

Access & limits

• Account: a free Wedding Harmony account with at least one wedding, on iOS or Android. Approving a connection or creating a key needs Sign in with Apple; the connector itself works for any wedding that account can open.
• Plan: every tool is available on the free plan. Premium features inside the app (seating canvas, exports) do not change what the connector can do.
• Rate limit: 60 requests per minute per account. Over the limit you get 429 with Retry-After: 60.
• Keys: up to 10 live keys per account.
• Payments: none. The connector does not sell or unlock anything.
• Regions: available worldwide; data is processed and stored in the EU.

Errors

Data & privacy

An assistant sees exactly what the couple sees in the app for the weddings their account can open: guest names and contact details, RSVP answers, dietary needs, tasks, budget entries, vendors, songs, timeline and seating. Nothing about other users, and nothing the couple could not open themselves.

• Wedding Harmony does not send data to your assistant on its own. Every read and write happens because the assistant called a tool with the couple's key.
• What the assistant does with the data is governed by the assistant provider's terms, not ours. Couples should connect assistants they trust with their guests' details.
• Keys are stored hashed. Revoking one on the AI Assistants screen ends access at once.
• Writes are attributed inside the app the same way manual edits are; songs added through a connector are marked as added by "AI assistant".

See the Privacy Policy and Terms of Service for the full picture of how wedding data is handled.

Support