# VoiceHug MCP server

VoiceHug runs a remote MCP (Model Context Protocol) server so an AI assistant can organize VoiceHugs for a user: start one, invite contributors by email, remind people who have not recorded, and produce the finished audio gift. The assistant acts as the signed-in user, with exactly the access they have on the website.

## Endpoint

- URL: https://www.voicehug.co/api/mcp
- Transport: Streamable HTTP (stateless; no session required)
- Server name: `voicehug`

## Authentication

- OAuth 2.1 authorization code flow with PKCE (S256). VoiceHug accounts live in Supabase Auth, which is the authorization server.
- Authorization server (issuer): https://eopicphyydfljtyynhfb.supabase.co/auth/v1
- Discovery: an unauthenticated request to the endpoint answers 401 with a WWW-Authenticate header pointing at the protected resource metadata, https://www.voicehug.co/.well-known/oauth-protected-resource.
- Scopes: request email and profile, or none. Access is not divided by scope: an approved app can do anything the tools above allow, as the user who approved it. The consent screen says so.
- Client registration: dynamic client registration is not available. To connect an app, email hello@voicehug.co with the app name, its redirect URI(s), and whether it is a public or confidential client, and we will send back a client ID (and secret for confidential clients).
- Users sign in with a one-time code sent to their email; there are no passwords.

## Tools

| Tool | What it does | Inputs |
|---|---|---|
| `whoami` | Which VoiceHug account the connection is signed in as. | none |
| `list_voicehugs` | The VoiceHugs the user organizes, newest first, with contributor counts. | status? (active | complete), limit? (1–50, default 20) |
| `get_voicehug` | Full status of one VoiceHug: who has recorded, payment status, links to share, and suggested next steps. | voicehug_id |
| `create_voicehug` | Start a new VoiceHug for a recipient. | recipient_name, occasion_type?, occasion_other?, occasion_date? (YYYY-MM-DD), organizer_message? (≤700 chars) |
| `update_voicehug` | Change recipient, occasion, date, or the note shown to contributors. | voicehug_id plus any of the create fields |
| `add_contributors` | Invite people by email; each gets a personal recording link. Already-invited people are skipped. | voicehug_id, contributors[] (email, personalized_note?; up to 25), send_invitations? (default true) |
| `remove_contributor` | Remove a contributor, and their recording if they made one. Destructive. | voicehug_id, contributor_id |
| `send_reminder` | Email a reminder to someone who has not recorded yet (at most every 48 hours per person). | voicehug_id, contributor_id or contributor_email, custom_message? (≤500 chars) |
| `get_payment_status` | Whether payment is needed before the final mix, and whether it has been made. | voicehug_id |
| `get_checkout_link` | The payment page for groups above the free tier (one-time $9.99 USD). The user pays on the page; the tool never handles payment details. | voicehug_id, referral_code? |
| `generate_final_mix` | Mix the recordings into the finished gift and return the link for the recipient. | voicehug_id, wait? (default true; false returns immediately) |

## Example requests

- "Create a VoiceHug for my mum's 70th birthday on 12 October and invite sam@example.com, priya@example.com and leo@example.com."
- "Who hasn't recorded yet for Mum's VoiceHug? Send them a reminder."
- "Generate the final mix and give me the link to send her."

## Access requirements

- A free VoiceHug account (sign-up happens on the consent screen with an emailed one-time code).
- Free for the organizer plus up to 5 contributors. Larger groups need a one-time $9.99 (USD) payment before the final mix, completed by the user on VoiceHug's checkout page (Polar). No subscription.
- Recording happens in the browser. The server returns links for the organizer and contributors to record; it cannot record or upload audio itself.
- Rate limits: 120 requests per minute per IP address. Reminders are limited to one per contributor every 48 hours, and none within 24 hours of the invitation.

## Data handling

- The server reads and changes only VoiceHugs the signed-in user organizes, through the same database access rules as the website.
- It stores nothing of its own. Contributor emails and notes you pass in are saved to the VoiceHug and used to send invitation and reminder emails.
- It never returns audio files or storage URLs; the finished gift is shared through its /hug link.
- Privacy policy: https://www.voicehug.co/privacy. Terms: https://www.voicehug.co/disclaimer. Security reports: hello@voicehug.co.

## More

- [Developer & agent resources](https://www.voicehug.co/developers)
- [agents.md](https://www.voicehug.co/agents.md)
- Contact: hello@voicehug.co