Joy MCP tools

MCP tool joy_list_events

Returns every Joy event your account can open, as owner or collaborator. Use event_id from each item as the event_id parameter of the other endpoints.

Parameters

No parameters.

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_list_events",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "events": [
      {
        "event_id": "evt_8KQ2mZ",
        "name": "Maria and Tom",
        "date": "2027-06-12",
        "role": "owner",
        "website": "https://withjoy.com/maria-and-tom"
      }
    ]
  },
  "isError": false
}

MCP tool joy_list_guests

Returns guests in guest list order with their party, tags and answers to each RSVP question. Filter by RSVP status, tag or name to narrow it down. Pages hold up to 500 guests; pass next_cursor back as cursor.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_list_guests",
    "arguments": {
      "event_id": "evt_8KQ2mZ",
      "rsvp": "attending",
      "tag": "Reception",
      "limit": 500
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guests": [
      {
        "guest_id": "g_4d21",
        "first_name": "Ana",
        "last_name": "Lopez",
        "email": "ana@example.com",
        "party": "Lopez",
        "tags": [
          "friends"
        ],
        "rsvp": "attending",
        "answers": {
          "Meal choice": "Vegetarian"
        }
      },
      {
        "guest_id": "g_4d22",
        "first_name": "Luis",
        "last_name": "Lopez",
        "email": null,
        "party": "Lopez",
        "tags": [
          "friends"
        ],
        "rsvp": "attending",
        "answers": {
          "Meal choice": "Fish"
        }
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

MCP tool joy_get_guest

Returns one guest with the full set of RSVP answers and which emails were sent to them. Use it before changing an RSVP or contacting the guest.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_get_guest",
    "arguments": {
      "event_id": "event_8c41d2",
      "guest_id": "guest_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guest_id": "g_4d21",
    "first_name": "Ana",
    "last_name": "Lopez",
    "email": "ana@example.com",
    "phone": null,
    "party": "Lopez",
    "plus_ones": 0,
    "tags": [
      "friends"
    ],
    "rsvp": "attending",
    "answers": {
      "Meal choice": "Vegetarian",
      "Dietary notes": "No nuts"
    },
    "emails": [
      {
        "subject": "Two weeks left to RSVP",
        "sent_at": "2027-05-29T10:00:00Z",
        "opened": true
      }
    ]
  },
  "isError": false
}

MCP tool joy_get_rsvp_summary

Returns counts of guests who are attending, declined or have not responded, and for each RSVP question how many guests gave each answer. The counts match the Guest List screen.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_get_rsvp_summary",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "evt_8KQ2mZ",
    "guests_total": 120,
    "attending": 74,
    "declined": 9,
    "no_response": 37,
    "questions": [
      {
        "question": "Meal choice",
        "answers": {
          "Beef": 31,
          "Fish": 24,
          "Vegetarian": 19
        }
      }
    ]
  },
  "isError": false
}

MCP tool joy_list_schedule

Returns the events on your Schedule page in time order. Privacy says whether everyone or only specific guests see an event. Use schedule_item_id with update_schedule_event.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_list_schedule",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "schedule": [
      {
        "schedule_item_id": "sch_41",
        "name": "Welcome dinner",
        "start": "2027-06-11T18:00:00",
        "time_zone": "Europe/Rome",
        "venue": "Osteria del Ponte",
        "dress_code": "Smart casual",
        "privacy": "everyone"
      }
    ]
  },
  "isError": false
}

MCP tool joy_list_registry_gifts

Returns everything on your registry: gifts from any store and cash funds. Each item shows how many are still wanted and whether any were purchased or reserved.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_list_registry_gifts",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "gifts": [
      {
        "gift_id": "gft_7731",
        "title": "Stand mixer",
        "store": "example-store.com",
        "price": "329.00",
        "quantity": 1,
        "purchased": 1,
        "most_wanted": true
      },
      {
        "gift_id": "gft_7740",
        "title": "Honeymoon fund",
        "type": "cash_fund",
        "raised": "450.00"
      }
    ]
  },
  "isError": false
}

MCP tool joy_list_received_gifts

Returns what the Track tab of your Registry shows: the guest who bought each physical gift, the quantity and order info, and what each guest put into a cash fund. Each row says whether a thank-you was sent.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_list_received_gifts",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "gifts": [
      {
        "gift_id": "gft_7731",
        "item": "Stand mixer",
        "from": "Ana Lopez",
        "quantity": 1,
        "received_at": "2027-05-20",
        "thank_you_sent": false
      },
      {
        "gift_id": "gft_7740",
        "item": "Honeymoon fund",
        "from": "Luis Lopez",
        "amount": "100.00",
        "received_at": "2027-05-22",
        "thank_you_sent": true
      }
    ]
  },
  "isError": false
}

MCP tool joy_add_guest

Adds one guest to the guest list. Guests with the same party value are grouped and can RSVP for each other. It sends nothing to the guest and is undone by removing the guest, so it runs without asking.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_add_guest",
    "arguments": {
      "event_id": "evt_8KQ2mZ",
      "first_name": "Ada",
      "last_name": "Okafor",
      "email": "ada.okafor@example.com",
      "party": "Okafor",
      "name_on_envelope": "The Okafor Family",
      "tags": [
        "Bride family"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guest_id": "g_4e08",
    "first_name": "Maria",
    "last_name": "Porter",
    "party": "Porter family",
    "name_on_envelope": "The Porter Family",
    "tags": [
      "family"
    ],
    "rsvp": "no_response"
  },
  "isError": false
}

MCP tool joy_update_guest

Changes the fields you pass and leaves the rest. Setting rsvp_answers records the answer as if the guest gave it; null removes an answer. It sends nothing to the guest and one more call reverts it, so it runs without asking.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_update_guest",
    "arguments": {
      "event_id": "event_8c41d2",
      "guest_id": "guest_8c41d2",
      "fields": "fields"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guest_id": "g_4d22",
    "email": "luis@example.com",
    "rsvp": "attending",
    "answers": {
      "Meal choice": "Fish"
    }
  },
  "isError": false
}

MCP tool joy_assign_guest_tags

Adds or removes tags on many guests in one call. New tags are created. Tags can limit who sees a private event or an RSVP question, so check them before the next send. It sends nothing and is undone with one call.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_assign_guest_tags",
    "arguments": {
      "event_id": "event_8c41d2",
      "guest_ids": [
        "guest ids"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "updated": 12,
    "added": [
      "family"
    ],
    "removed": []
  },
  "isError": false
}

MCP tool joy_update_schedule_event

Changes the fields you pass on one Schedule event. The new time or venue shows on your public website at once, so guests can see it before any email goes out. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_update_schedule_event",
    "arguments": {
      "event_id": "event_8c41d2",
      "schedule_item_id": "schedule_item_8c41d2",
      "fields": "fields"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "schedule_item_id": "sch_41",
    "name": "Welcome dinner",
    "start": "2027-06-11T19:00:00",
    "time_zone": "Europe/Rome",
    "privacy": "everyone",
    "status": "updated"
  },
  "isError": false
}

MCP tool joy_add_registry_gift

Adds a gift to your registry from a product page. Joy reads the title and price from the page when it can; set them yourself otherwise. Mark it Our Most Wanted to highlight it. It reaches no one directly and one removal undoes it, so it runs without asking.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_add_registry_gift",
    "arguments": {
      "event_id": "event_8c41d2",
      "product_url": "https://example.com"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "gift_id": "gft_7752",
    "title": "Cast iron pan",
    "price": "89.00",
    "quantity": 1,
    "most_wanted": false
  },
  "isError": false
}

MCP tool joy_send_rsvp_reminder

Sends the Joy RSVP reminder. Without guest_ids it goes to every guest with no response. Guests with no email are skipped and counted in the response. Email is free; text needs Messaging Plus. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_send_rsvp_reminder",
    "arguments": {
      "event_id": "evt_8KQ2mZ",
      "delivery": "email",
      "subject": "Two weeks left to RSVP"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "evt_8KQ2mZ",
    "status": "sent",
    "delivery": "email",
    "recipients": 35,
    "skipped_missing_email": 2,
    "rsvp_url": "https://withjoy.com/maria-and-tom/rsvp"
  },
  "isError": false
}

MCP tool joy_send_email_message

Sends a freeform email to the guests you pick by ID or tag, with a button to your event website. Guests without an email address do not get it. Scheduling for later needs Messaging Plus. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_send_email_message",
    "arguments": {
      "event_id": "event_8c41d2",
      "subject": "subject",
      "message": "message"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "message_id": "msg_2290",
    "status": "sent",
    "recipients": 74,
    "skipped_missing_email": 1
  },
  "isError": false
}

MCP tool joy_send_thank_you_note

Sends one thank-you to the guest who gave the gift, and marks the gift as thanked in the tracker. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "joy_send_thank_you_note",
    "arguments": {
      "event_id": "evt_8KQ2mZ",
      "gift_id": "gft_7731",
      "subject": "Thank you, Ana",
      "message": "Ana, thank you for the stand mixer and for the gift to our honeymoon fund. The mixer has made bread every weekend since we got home. Maria and Tom"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "gift_id": "gft_7731",
    "to": "Ana Lopez",
    "status": "sent",
    "thank_you_sent": true
  },
  "isError": false
}