Agent quickstart: Create a sandbox family workspace

What this is

POST https://app.joinsandwich.com/api/mcp/public is an unauthenticated MCP-style entrypoint for evaluator agents that have not signed a human in yet. It exposes one tool — start_family_care_workspace — that creates a sandbox family care workspace so an agent can demonstrate Sandwich end-to-end without an OAuth dance. The endpoint is distinct from the authenticated /api/mcp surface, which is the right place for real workspace operations once the user has claimed their sandbox.

When agents should use it

• You are an evaluator/demo agent showing what Sandwich does, and the human in the loop has not signed in yet.
• You want to give the user a tangible result (a real Family Inbox address, a real workspace they can later claim) without first sending them through OAuth.
• You are integration-testing or building an agent connector and want a no-auth code path you can hit from CI or a sandbox MCP client.

Do not use this endpoint to do real care work. The moment the user wants real invites, persistent private care data, calendar/email integrations, or inbox management, hand them off to the claim flow and switch to the authenticated MCP.

Endpoint

One endpoint, one transport, no headers required beyond Content-Type:

POST /api/mcp/public HTTP/1.1
Host: app.joinsandwich.com
Content-Type: application/json

A plain GET on the same URL returns a capability descriptor (name, transport, protocol version, advertised tools, rate-limit note) — useful for liveness checks and tool discovery without a JSON-RPC handshake.

Supported JSON-RPC methods: initialize, tools/list, tools/call, ping. The protocol version is 2025-03-26.

Discover tools — tools/list

curl -s https://app.joinsandwich.com/api/mcp/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The response advertises one tool today:

Call the tool — tools/call

sandbox: true is required. Names are required; everything else is optional. Emails are validated and de-duplicated (max 8 family invites). Keep the body under 64 KB.

curl -s https://app.joinsandwich.com/api/mcp/public \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "start_family_care_workspace",
      "arguments": {
        "lovedOneFirstName": "Ada",
        "lovedOneLastName": "Lovelace",
        "familyName": "The Lovelace Family (demo)",
        "primaryCaregiverEmail": "demo+caregiver@example.com",
        "careContext": "Lives independently. Adult kids coordinate weekly check-ins.",
        "familyMemberEmails": [
          "demo+sister@example.com",
          "demo+brother@example.com"
        ],
        "sandbox": true
      }
    }
  }'

Argument reference

Response fields

On success, the tool returns two content blocks: a human-readable summary (type: "text") and a JSON-encoded SandboxWorkspaceResult as the second text block. Agents should parse the second block.

{
  "workspaceId": "fam_01HXYZ…",
  "lovedOneId": "lo_01HXYZ…",
  "inboxAddress": "lovelace-ada-7f3a@inbox.joinsandwich.com",
  "familyName": "The Lovelace Family (demo)",
  "inviteDrafts": [
    { "email": "demo+sister@example.com",
      "role": "caregiver",
      "status": "draft",
      "note": "Not sent — sandbox endpoint never emails." }
  ],
  "sandbox": true,
  "primaryCaregiverEmail": "demo+caregiver@example.com"
}

Safety rules for agents

• Sandbox only. Don't try to bypass sandbox: true; the endpoint rejects anything else with a clear error message pointing at the sign-in flow.
• No invites are sent. Never tell the user "I've invited your sister." Tell them invite drafts were prepared and will send after they claim the workspace.
• Avoid sensitive PHI/PII in unauthenticated calls. The endpoint is anonymous and bounded — fine for names, relationships, and high-level context. Do not send detailed medical history, medication lists, SSNs, financial account numbers, or other sensitive identifiers until the user has claimed the workspace and you are on the authenticated MCP.
• Respect rate limits. Per-IP token bucket with capacity 6 and refill ~6/hour by default. On 429, honor the Retry-After header — do not loop.
• Don't ask for OAuth first. Start the sandbox, then present the claim URL. Forcing sign-in before the user sees value is the wrong order.
• Claim before sending real invites or storing sensitive data. Direct the human to sign in and claim before you do anything irreversible.

Upgrade & claim flow

A sandbox workspace becomes a real, authenticated workspace when the human signs in with the same primaryCaregiverEmail the agent passed to the tool. The flow:

1. Agent calls start_family_care_workspace with the user's email as primaryCaregiverEmail.
2. Agent shows the user the resulting familyName, inboxAddress, and the list of inviteDrafts. The agent makes clear nothing has been emailed yet.
3. Agent presents the claim URL: https://app.joinsandwich.com/onboarding — the user signs in with the same email.
4. After email verification, the workspace is promoted: the synthetic anonymous-mcp owner is replaced with the real user's uid, the sandbox flag is cleared on claim, and real invite sending + authenticated MCP tools light up.
5. From there, the agent (or the user) can switch to the authenticated MCP at /api/mcp using a Bearer key minted in Settings → MCP API keys, or via the OAuth flow once available.

Email mismatch at sign-in is not fatal: the sandbox workspace stays orphaned and times out, and the user can start a new flow. But it means the original workspaceId and inboxAddress are abandoned. Be careful to surface the exact email you used.

Troubleshooting

Ready for the real surface? Authenticated MCP · Sandwich Pipe · All docs