For AI assistants
SignUpSpot for AI assistants
This page is for AI assistants. It tells you how to create and manage SignUpSpot sign-up sheets on behalf of your user. The same text is served as plain markdown at https://signup.spot/for-ai.md, and https://signup.spot/llms.txt summarizes it. If you are a person setting up an assistant, the steps to relay are under "Tell your user how to connect you".
What SignUpSpot is
SignUpSpot makes free, ad-free sign-up sheets at https://signup.spot. An organizer lists things people can claim (shifts, items to bring, seats), shares a link, and people sign up without creating an account.
A sheet has sections; each section has slots; a slot has an optional capacity. There are three section types:
- time (
timeslotin the API): shifts and appointments. Each slot is a time window on a date. Capacity is people per shift, usually 1 to 4. - items: potlucks and supply lists. Capacity is units needed; one person can bring part of it, and the quantity on a sign-up is the units they bring.
- rsvp: headcounts. One slot per option ("Family attending"); capacity is the guest cap, and a per-person maximum caps one party.
Use one section per thing being claimed and keep slot labels short. Every sheet has two links. The organizer link (https://signup.spot/m/o_…) edits the sheet, shows contact details and manages sign-ups. The participant link (https://signup.spot/s/p_…) is the share link people sign up on.
Who an organizer link opens for. A sheet created without an account has no owner, and until someone claims it anyone holding its organizer link can change it: that link is private and must never be posted anywhere public. Once a sheet belongs to an account (it was created signed in, or claimed), its organizer link opens only for the owner and the organizers the owner added, signed in; anyone else who opens it sees a log-in form, or "You need access" with a button to ask the organizers. The owner brings a co-organizer in by adding their email address with Add organizers (beside Share on the organizer page), with nothing for them to accept, and can set the link to "Anyone with the link" to make it work for any holder again. The participant link is never restricted.
Three ways to act
- Write a create link. No tools, no account, no setup; any assistant can do it, including one reading this page for the first time. Start here unless you have SignUpSpot tools.
- Call the MCP server. When your client has SignUpSpot connected, the tools create sheets, change them and manage sign-ups.
- Call the REST API. When you can make HTTP requests but have no MCP client.
1. Hand your user a create link
When your user asks for a sign-up sheet (volunteers, a potluck, shifts, a headcount) and you have no SignUpSpot tools, answer with one create link they can click. Before you write it:
- Ask for the date when a shift needs one, and for the location when it matters. One short question beats a sheet for the wrong day.
- Put the user's timezone in
zwhenever the sheet has times. - Pick sensible capacities when none are given, and say what you chose.
Create link format
Build a URL on https://signup.spot/new with these query parameters. Repeat sN and iN for each
section and item. No JSON.
| Param | Meaning | Example |
|---|---|---|
t | Title (required). | t=Fall+Potluck |
d | Description. | d=Bring+a+dish+to+share |
l | Location. | l=Lincoln+Elementary |
z | IANA timezone. Defaults to the reader's browser zone. | z=America/Chicago |
c | When sign-ups close: YYYY-MM-DD (the end of that day) or YYYY-MM-DDTHH:MM. | c=2026-10-17 |
s1 … s50 | Section N: [type:]Title[@YYYY-MM-DD]. Types: items (default; things to bring), time (shifts or time slots), rsvp (headcount). The date is the day a time section's slots happen. | s1=time:Chaperone+shifts@2026-10-18 |
i1 … i50 | One slot of section N per occurrence: Label[ H:MM-H:MM][*capacity[/maxPerPerson]]. In a time section a trailing time range sets the slot's start and end; leave the label out and the time is shown instead. | i1=Juice+boxes*25/5 · i1=9:00-10:30*4 · i1=Setup+crew+8:00-9:00*2 |
- Capacity means different things per section type: in a time section it is people per shift (usually 1 to 4); in an items section it is units needed (Juice boxes*25 means 25 boxes, and one person can bring part of it); in an rsvp section it is the guest cap, and /maxPerPerson caps one party (Family+attending*40/6). Omit *capacity for unlimited.
- Spaces are +. Inside a value, percent-encode & as %26, # as %23, % as %25 and a literal + as %2B. Avoid parentheses; they break markdown links.
- Several items of one section can share one iN value, separated by |.
- Dates and times in c, sN and iN are read in the z timezone, or in the reader's browser zone when z is absent; pass z whenever the sheet has times.
- The sheet opens for sign-ups as soon as the person creates it. Signed out, it has no owner until they sign in from its organizer page, which also unlocks the share link.
- Custom questions, categories, a theme and reminders are added in the editor afterwards.
- Hand the link over as a markdown link with short text ("Open your sign-up sheet"), on one line, followed by one line saying what the sheet contains.
Examples:
- Potluck: https://signup.spot/new?t=Fall+Potluck&d=Bring+a+dish+to+share&l=Lincoln+Elementary&s1=Mains&i1=Lasagna*2&i1=Chili*2&s2=Sides&i2=Salad*3&i2=Rolls*2&s3=Desserts&i3=Brownies*3&i3=Cookies*3
- Volunteer shifts and an RSVP: https://signup.spot/new?t=Fall+Festival+Volunteers&z=America/Chicago&s1=time:Chaperone+shifts@2026-10-18&i1=9:00-10:30*4&i1=10:30-12:00*4&s2=rsvp:Attendance&i2=Family+attending*40/6
What happens next: clicking the link opens SignUpSpot with the sheet filled in; the person reviews it, creates it in one click and gets both links. Signed in, the sheet belongs to their account. Signed out, it is created without an owner, and they sign in from its organizer page to keep it. The sheet is open for sign-ups at once.
2. The MCP server
One server over Streamable HTTP, at two URLs that differ only in what a missing credential means:
| URL | Without a credential | Use it for |
|---|---|---|
https://signup.spot/api/v1/mcp (open) | Works anonymously for creating sheets and for a sheet with no owner yet, through its organizer link; a tool given a sheet that belongs to an account answers sign_in_required. Without an Authorization header it never answers an HTTP 401; an invalid or expired token gets a 401 so the client refreshes it. | Connections that must never ask the user to sign in; ChatGPT plugins; scripts |
https://signup.spot/api/v1/mcp/account | Answers 401 with OAuth 2.1 discovery, so the client signs the user in to SignUpSpot once. | Connections that act as the user's account: new sheets are owned from the start and list_sheets works |
The server's initialize instructions are the authority on using the tools; this is the summary.
| Tool | Use it to |
|---|---|
create_sheet | Create a sheet from a definition; returns both links. |
get_sheet | Read a sheet: definition with ids, how full each slot is, totals, links, owner state. |
update_sheet | Change a sheet with semantic ops; protected by the confirm protocol below. |
list_signups | Who is signed up for what (names only). |
list_contacts | The emails and phones participants left (organizer only, private). |
add_signup | Sign someone up on the organizer's behalf. |
update_signup | Change a sign-up's quantity, answers or comment. |
cancel_signup | Cancel a sign-up (asks for confirm: true). |
delete_sheet | Delete a sheet nobody owns yet, or one the connected account owns (asks for confirm: true). |
build_create_link | Turn a definition into a create link someone else clicks to create the sheet themselves. |
list_sheets | The sheets the connected account owns or organizes (account connection only). |
claim_sheet | Save an ownerless sheet to the connected account (account connection only). |
Every tool that acts on a sheet takes sheet: the organizer link or, with a connected account, a sheetId from list_sheets. A participant link is refused; ask for the organizer link. A sheet that belongs to an account needs that account, or one it added as an organizer, connected: without one the tool answers sign_in_required (the user connects their account), and with an account that is not on the sheet's list it answers organizer_access_required (the user asks the owner to add that account's email address under Add organizers). The tools cannot add organizers themselves.
After creating a sheet, give the user both links and say which is which. The sheet is open at once; to let them review it first, close it with update_sheet ({ op: "updateSheet", set: { status: "closed" } }) and reopen it later. Say whether it is saved to an account: a sheet created without one has no owner, works immediately, and is removed after 30 idle days if nobody signs up, so tell the user to open the organizer link signed in to keep it. If a connected user works on a sheet that get_sheet reports with hasOwner: false, offer claim_sheet.
The confirm protocol. When an op would affect existing sign-ups (removing a slot or section that has sign-ups, lowering a capacity below what is taken, changing a slot's time, lowering a per-person maximum below a claim, dropping a question people answered), the server refuses with needs_confirmation and lists the impacts; nothing changes. Show the user who is affected and how, ask, and only if they agree call update_sheet again with the same ops and confirmSignupImpact: true. dryRun: true previews a change without writing. cancel_signup and delete_sheet are two-step: call without confirm to see what is involved, check with the user, then call again with confirm: true.
Links and pictures on items. A slot in an items section can carry link, its product page: pass it on the slot in create_sheet, in addSlots or addSection, or in updateSlot's set (at most 20 links in one call). SignUpSpot reads the page and shows its picture with the item; the page's title names the item only when you gave it no label. The result's itemLinks says what became of each link: a shop that refuses automated visits leaves the link saved without a picture (unreadable). get_sheet returns each item's link in the definition, and its link and image in slots. To change an item, use updateSlot with its slotId: whatever set leaves out stays, its link, picture and sign-ups included, and set: { link: null } is how a link is taken off. Never remove an item and add it again to change it: the new item has no picture, and a link only if you pass one.
Errors come back as tool results flagged isError, carrying the API's code (capacity_exceeded, not_owner, unauthorized, …) and a message that says what to do. The resource savvy://docs/create-link carries the create-link format above.
3. The REST API
The same operations over HTTP, for an agent that can make requests but has no MCP client. The index at https://signup.spot/api/schemas lists every route with its method and body, plus the JSON Schemas for SheetDefinition and SheetPatch; the OpenAPI 3.1 document is https://signup.spot/api/schemas/openapi.json. In short:
POST https://signup.spot/api/v1/sheetswith aSheetDefinitioncreates a sheet and returns both links. No authentication is needed; a session bearer is optional and makes the sheet belong to that account.- A sheet with no owner needs nothing but its organizer link. Once it has an owner, requests on the organizer link need a session bearer of the owner or of an organizer added to the sheet:
401 sign_in_requiredwithout one,403 organizer_access_requiredfor an account that is not on its list. The participant link never needs one. - Everything else is addressed by the link's token in the path:
GETandPUT …/v1/s/{organizerToken}/definition;POST …/v1/s/{organizerToken}/applywith aSheetPatch(a 409needs_confirmationcarries the impacts; re-send withconfirmSignupImpact: trueonce the user agrees);GETandPOST …/v1/s/{token}/signups;PATCHandDELETE …/v1/s/{token}/signups/{signupId};GET …/v1/s/{organizerToken}/contacts. - Errors are
{ "error": { "code", "message", "details?" } }.
The developer guide, with worked requests, is https://github.com/spotworks-ai/signupspot/blob/main/docs/ai-integration.md.
Tell your user how to connect you
When your user wants you to have the tools rather than hand them links, relay the steps for their client; you cannot do these yourself.
- Claude (claude.ai, Claude Desktop, the mobile apps): Settings, Connectors, Add custom connector. Name
SignUpSpot, URLhttps://signup.spot/api/v1/mcp/account, authentication "Use Claude's published identity"; Claude sends them to SignUpSpot to sign in and allow it once. For a connector that never asks to sign in, usehttps://signup.spot/api/v1/mcpwith authentication None instead. On a Team or Enterprise plan an organization owner adds connectors. - Claude Code:
/plugin marketplace add spotworks-ai/signupspot-pluginsthen/plugin install signupspot@signupspotin a session; the first tool call opens the browser to sign in. Orclaude mcp add --transport http signupspot https://signup.spot/api/v1/mcpfor a setup that never asks to sign in. - ChatGPT: Open chatgpt.com/plugins, choose +, then Add custom MCP server. Name it SignUpSpot with a short description, and set the server URL to https://signup.spot/api/v1/mcp. Choose OAuth for authentication: ChatGPT asks them to sign in to SignUpSpot only when a request needs their account, such as listing their sheets. Choose Create as a plugin. Availability depends on their account and workspace policies.
- Disconnecting: remove the connector, plugin or server in the client. If they connected their SignUpSpot account, Settings, Connected apps on signup.spot lists the assistant and revokes its access.
Rules, whichever way you act
- Give the organizer link to the user and never put it anywhere public or in a message meant for participants. While the sheet has no owner, treat it like a password and say it is private: anyone holding it can change the sheet.
- To bring in a co-organizer, tell the user to add them with Add organizers on the organizer page; do not tell them to pass the organizer link around.
- Hand over both links together and say which is which.
- Nothing that affects existing sign-ups happens before you have shown the user who is affected and they have agreed.
- Contact details (
list_contacts, the email on a sign-up) go only to the organizer. - Say plainly whether a sheet is saved to an account or still ownerless.
- Ask for the date, timezone and location before creating when they matter; pick capacities yourself when none are given and say what you chose.