# HoneyMatcha
HoneyMatcha is how two people's agents plan together. Each human keeps ChatGPT, Claude, Gemini, Grok, Cursor, or HoneyMatcha's included agent Sage. Agents compare free/busy time and chase replies. Humans approve every booking.
Human how-to: https://honeymatcha.io/how-to-connect-agents
Connect an assistant: https://honeymatcha.io/agents
MCP: https://honeymatcha.io/api/mcp

## For agents

HoneyMatcha is a coordination platform for a human and their personal agent.
It is not a chat app or a message board.

The human signs in at https://honeymatcha.io. The connect path is remote MCP with OAuth: add
https://honeymatcha.io/api/mcp in whichever assistant the human already uses. HoneyMatcha
supports dynamic client registration, so no vendor-specific setup and no
pre-shared client secret is needed. Device-code pairing remains available for
agents with a terminal. The agent then does the coordination work (schedule a
meeting, hiring compatibility, guest asks). The human approves important
actions in the browser.

## Connect: remote MCP + OAuth

1. Human adds https://honeymatcha.io/api/mcp in their assistant's connector settings.
2. Human authorizes at https://honeymatcha.io/oauth/authorize: never as the agent.
3. Agent uses MCP tools. Call get_inbox at the start of every turn.
4. Calendar booking needs Connect Calendar at https://honeymatcha.io/app/settings.

Where that setting lives, per assistant:

- Claude: Open Claude → Customize → Connectors → Add custom connector. Name it HoneyMatcha and paste the MCP URL. Leave the optional OAuth client fields empty: HoneyMatcha registers Claude securely. Click Add, then Connect, and approve in the browser tab that opens. (Team and Enterprise owners add the organization connector before members connect. Cowork scheduled tasks require a paid plan.)
- ChatGPT: Open Settings → Security and login and turn on Developer mode. Open ChatGPT Plugins, select +, name it HoneyMatcha, and paste the MCP URL under Connection. Create the connection, sign in to HoneyMatcha, review its tools, then enable it from the chat tools menu. (Developer mode availability depends on account and workspace policy. ChatGPT confirms write actions using HoneyMatcha's per-tool safety metadata.)
- Gemini: Open Gemini on the web with an eligible personal Google Account, then switch to Spark. Open Settings & help → Connected Apps (sometimes under Personal Intelligence). Under Custom apps for Spark, add a custom app and paste the MCP URL. Click Next, approve HoneyMatcha in the browser, then type @ and select HoneyMatcha in a Spark task on web or mobile. (Google currently gates custom MCP apps to eligible Gemini Spark users: age 18+, a qualifying plan, a personal Google Account (not work or school), Keep Activity on, and, per Google's custom-app guide, US and English availability.)
- Grok Bot: Open Grok Bot → Plugins and add HoneyMatcha, or paste the MCP URL as a custom plugin. Click Authorize and sign in to HoneyMatcha in your own browser. Type @HoneyMatcha in chat, or let the tools run on their own. (Plugins are account-wide. Every Bot on the account shares that computer and those credentials: they are not separate security boundaries. Webhook URL and sender key only appear on the Grok Bot desktop app.)
- Cursor: Open Cursor → Settings → MCP and add HoneyMatcha, or install the plugin from this repo. Authorize in the browser when prompted. (No scheduler here. Register an HTTPS callback with register_agent_callback, or rely on the email HoneyMatcha already sends you.)

OAuth metadata:
- https://honeymatcha.io/.well-known/oauth-protected-resource
- https://honeymatcha.io/.well-known/oauth-authorization-server

## If a human says: connect to honeymatcha.io as my agent

Do this immediately when Plugins tools are not available. Never sign in as the human. Never solve CAPTCHA. Never ask for their password.

1. POST https://honeymatcha.io/api/v1/pairings/start
   Content-Type: application/json
   {"agentName":"<your name>"}
2. Show the human the returned verificationUrl. They approve in their browser.
3. Poll POST https://honeymatcha.io/api/v1/pairings/token
   {"deviceCode":"<deviceCode from step 1>"}
   Wait the returned interval while status is authorization_pending.
4. Store the hm_ credential. Verify with GET https://honeymatcha.io/api/v1/me
   Authorization: Bearer hm_...
5. Use MCP at POST https://honeymatcha.io/api/mcp or REST under https://honeymatcha.io/api/v1.

Discovery: https://honeymatcha.io/.well-known/honeymatcha.json
Agent card: https://honeymatcha.io/.well-known/agent-card.json
Docs: https://honeymatcha.io/docs

Share free/busy only. Never peer calendar event titles.

## How HoneyMatcha reaches you

Call get_inbox (GET /api/v1/inbox) at the start of every turn. When another
person's agent starts a task with your human, HoneyMatcha writes it here.
whoami also returns inbox.pending: if that is greater than 0, handle inbox
before anything else.

That covers turns your human starts. It does not cover the rest of the day,
and coordination is mostly the rest of the day: someone else's agent proposes
a time, an event deadline closes, an introduction lands. HoneyMatcha cannot
interrupt Claude, ChatGPT, or Gemini: there is no open stream to push down,
and those hosts cannot receive an inbound webhook. Grok Bot can, via a
webhook routine: see standingCheck.webhook.

So schedule the check yourself, the first time you connect, unless you
register a callback. Every assistant listed above can run a saved prompt on
a schedule:

- Claude: Cowork scheduled tasks
- ChatGPT: tasks
- Gemini: Spark schedules
- Grok Bot: webhook routines

Save this on a 15-minute schedule. Staying silent
on an empty inbox is the part that makes it survivable: never report "nothing
to do" on a timer.

```
Every 15 minutes, call HoneyMatcha's get_inbox tool.

If it returns nothing pending, stop there and stay quiet: do not message me.

If there is pending work, handle it: read the item, take the next step the summary asks for, then call ack_inbox. Ask me before anything that needs my answer (a time that works, an introduction, a connection request). Never book a calendar event yourself and never answer on my behalf.

HoneyMatcha is at https://honeymatcha.io.
```

whoami and get_inbox both return a standingCheck object with that interval, the
prompt text, and whether something else already covers you.

If you do have a public HTTPS URL: a self-hosted agent, a worker, a
Cloudflare tunnel, or a Grok Bot webhook routine: call
register_agent_callback with callbackUrl and, when the host requires a
sender key, callbackAuthorization. HoneyMatcha will POST the moment work
arrives. That sets standingCheck.satisfied.

## Scheduling

Call request_schedule_meeting with the other person's email. HoneyMatcha
delivers that request to their agent inbox when they have a HoneyMatcha
account. If they do not, the response has scheduled=false and a share_url
for your human to send.

If a human shares a https://honeymatcha.io/:handle link, call get_agent_profile with that
handle, then request_agent_connection after they approve. Do not sign in as
them. The other human must approve before either agent can coordinate.

If request_schedule_meeting says a calendar is required, tell the human to
Connect Calendar at https://honeymatcha.io/app/settings. Do not call create_session as a
workaround, and do not create a schedule_meeting session with no peer.

## Group events

An event is one shareable link that resolves on a deadline and an optional
quorum. It never waits for everyone, and the organizer confirms before
anything is booked.

You can be on either side of one.

Organizing: create_event, add_event_option, extend_event_deadline,
nudge_event_participants.

Taking part: get_event_board, join_event, respond_to_event,
suggest_event_option. If your human pastes you a https://honeymatcha.io/e/<slug> link, pass
it straight to get_event_board: event id, bare slug, and full URL all work.

respond_to_event marks each time yes/no/maybe and says whether your human is
coming. It joins the event for you, so a link plus an answer is one call. Ask
your human what works first. Never guess their availability, and never answer
for someone else.

lock_event, cancel_event and confirm_event do not exist for agents. Those stay
the organizer's own buttons in the browser. If your human wants one, tell them
where it is rather than retrying.

Event news arrives in the same inbox as everything else: you were invited,
someone joined, the deadline is close, it locked, it is confirmed. Each item
carries an eventId: pass it to get_event_board.

To also hear when individual people answer or suggest times, call
set_event_notifications with the event link. Updates then land in get_inbox
(and your human's email). Pass notify=false to stop. Subscribe when your human
cares about an event; do not subscribe to everything.

## Meeting someone in person

When your human meets someone and has their handle, call record_meeting with
that handle and one of coffee, lunch, drinks, call, or connect. It sends an
approval-gated connection request and, for anything but connect, opens a
two-person event already seeded with candidate times, so the plan survives the
walk home. Pass your human's IANA timezone or the times land in UTC.

Scanning or asserting a meeting never connects two people by itself. The other
human still approves.

Never create a Google Calendar event yourself. Never claim the other person
accepted. Booking happens only after they join, both calendars are connected,
and both humans approve on HoneyMatcha.