app.lovedone/family-inbox · 0.5.0

LovedOne Family MCP

Authenticated JSON-RPC for one household. The caller is a family member, or an agent holding that member’s key. This is not a multi-client vendor API. Providers use LovedOne Soft MCP.

POST https://api.lovedone.app/mcp/v1

What it does

After initialize and tools/list, a typical agent:

  1. get_user_profile — confirm workspace
  2. list_loved_ones — ids and @lovedone.app addresses
  3. list_family_members — who else is on the circle
  4. list_inbox_messages then get_inbox_message — mail as plaintext
  5. invite_family_member — invite a sibling (owner/coordinator)
  6. create_provider_code — mint a Soft link code (owner/coordinator)
  7. reply_to_inbox_message — reply with the same from/reply-to as the inbox UI (owner/coordinator)

Viewers can read. They cannot invite, mint codes, or reply. Allocate an inbox in the LovedOne UI.

It cannot: list another family, act as a vendor dashboard, return HTML or attachment bytes, or move money.

The other server

This spec

LovedOne Family MCP

api.lovedone.app/mcp/v1

One household. Mint at inbox.lovedone.app.

Sibling spec

LovedOne Soft MCP

api.lovedone.app/mcp/vendor/v1

One agency roster. Do not collect family keys to build this. Provider spec →

Authentication

Bearer key
Authorization: Bearer sk-sand-… minted at Settings → MCP API keys. Shown once. Stored as SHA-256.
Session cookie
In-app agents on inbox.lovedone.app. No extra key.
OAuth 2.1 + PKCE
Hosted connectors. Discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource on inbox.lovedone.app. Public scopes: profile:read, care_circle:read, care_circle:write. Writes require care_circle:write; a read-only token is denied with insufficient_scope. Viewers are still rejected.

Transport: JSON-RPC 2.0, one POST per call, protocol 2025-03-26. Handshake name app.lovedone/family-inbox, version 0.5.0. Prefer structuredContent. Rate limit 60/min per key. Alias: POST https://inbox.lovedone.app/api/mcp.

Tools

Public discovery (GET /mcp/v1 and /.well-known/mcp.json) lists the same catalog as the tool registry: name, one-line description, read or write, and the OAuth scope. Full inputSchema is only on authenticated tools/list.

ping
Read. No required scope. Uid, tenant, auth method.
get_user_profile
Read. Scope profile:read. Caller identity and workspace name/id/plan. Does not list sibling emails.
list_loved_ones
Read. Scope care_circle:read. Id, name, inbox address. Workspace resolved from the caller’s email.
list_family_members
Read. Scope care_circle:read. Role, relationship, status, email. Emails are personal data. Do not log them in third-party traces if you can avoid it.
list_inbox_messages
Read. Scope care_circle:read. lovedOneId required, limit 1–50. Subject, sender, 280-character plaintext preview. No HTML. Message category is omitted.
get_inbox_message
Read. Scope care_circle:read. messageId and lovedOneId required. Plaintext capped at 8 000 characters. Attachment metadata only. Ownership: message workspace and loved-one id must match. Message category is omitted.
invite_family_member
Write. Scope care_circle:write (OAuth). Invite a sibling by email with role coordinator or viewer. Same invite email as the dashboard. Owner/coordinator only.
create_provider_code
Write. Scope care_circle:write (OAuth). Mint a Soft provider link code for one loved one. Same helper as the loved-one page. Owner/coordinator only.
reply_to_inbox_message
Write. Scope care_circle:write (OAuth). Reply from family-inbox@m.lovedone.app with reply-to the loved one’s inbox. Owner/coordinator only.
onboard_loved_one
Write. Scope care_circle:write (OAuth). Muse-first setup: creates the caller’s workspace on first use (or adds to it), allocates the loved one’s @lovedone.app Family Inbox address, records the authorization attestation. Idempotent. The loved one is never emailed automatically.
get_onboarding_status
Read. Scope care_circle:read. Setup state (workspace, loved ones, inbox addresses, members) plus ordered next steps. Also served as the lovedone://dashboard MCP resource.

The server also speaks MCP resources (lovedone://dashboard, lovedone://help/getting-started, lovedone://help/connect-your-agent, lovedone://tools/catalog) and prompts (onboard_a_loved_one, invite_my_siblings, connect_a_care_provider). Discovery methods are public; tools/call and the dashboard resource require auth.

What it does not return

LovedOne Family MCP is senior tech support and Family Inbox coordination. It does not handle personal health data. HTML email and attachment bytes are withheld. Other families are unreachable.

SOC 2

Not attested yet. Type I is next. Type II needs a 6–12 month evidence window. Say that on questionnaires.

Secrets
Hashed keys. Revoke from Settings. Next call fails.
Audit
mcp_audit_log: caller, tool, timestamp, duration. Not message bodies.
Isolation
Every tool re-checks workspace membership. Admin SDK bypasses Firestore rules, so the handler is the control.
Transit / rest
TLS 1.2+, HSTS, Firestore AES-256. Vault adds application-layer AES-256.
Least privilege
HTML withheld. Attachment bytes withheld. Vault HMAC withheld. Other families unreachable.
Type II gaps
Key rotation SLA, SIEM export of audit logs, documented access-review cadence.

Connect

claude_desktop_config.jsonjson
{
  "mcpServers": {
    "lovedone-family": {
      "url": "https://api.lovedone.app/mcp/v1",
      "headers": { "Authorization": "Bearer sk-sand-REPLACE" }
    }
  }
}
initializebash
curl -s https://api.lovedone.app/mcp/v1 \
  -H "Authorization: Bearer sk-sand-…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"docs","version":"0"}}}'

In-product: inbox.lovedone.app/agents (lists both servers). Hub: docs.lovedone.app/mcp.html (canonical home of this file). Provider spec: docs.lovedone.app/mcp-vendor.html.