lovedone-app MCP API

openapi: 3.2.0
info:
  title: LovedOne public machine surface MCP API
  version: 1.0.0
  description: 'lovedone.app is a static consumer landing site (no private product CRUD). This document describes the public discovery files hosted here and the real authenticated Loved One family-inbox APIs hosted on inbox.lovedone.app / api.lovedone.app.


    Do not expect REST resources for messages or loved ones on this host. Family data is reached through the Model Context Protocol (JSON-RPC over Streamable HTTP) after the user mints a key or completes OAuth.


    Public pages on this host also negotiate `Accept: text/markdown` (acceptmarkdown.com).'
  contact:
    name: Terahertz, Inc. dba LovedOne
    email: hello@lovedone.app
    url: https://lovedone.app
  license:
    name: Proprietary — see Terms
    url: https://lovedone.app/terms
servers:
- url: https://lovedone.app
  description: Marketing site and public discovery (this spec's default server)
- url: https://api.lovedone.app
  description: Authenticated MCP (JSON-RPC). Not a REST CRUD API.
- url: https://inbox.lovedone.app
  description: Signed-in family inbox application
security: []
tags:
- name: MCP
  description: Authenticated family-inbox Model Context Protocol (hosted off this landing origin)
paths:
  /mcp/v1:
    servers:
    - url: https://api.lovedone.app
    get:
      tags:
      - MCP
      summary: MCP liveness / tool listing (no secrets)
      operationId: getMcpProbe
      description: JSON metadata about the LovedOne MCP server. Tool calls require POST + credentials.
      responses:
        '200':
          description: Server metadata and tool list
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
      - MCP
      summary: MCP JSON-RPC (Streamable HTTP)
      operationId: postMcp
      description: 'Authenticated JSON-RPC methods: initialize, tools/list, tools/call, ping.


        Live auth: `Authorization: Bearer sk-sand-...` minted at https://inbox.lovedone.app/settings/mcp-keys, or OAuth 2.1 + PKCE. Phase 1 API keys are not scope-gated (empty scope list = full caller access). OAuth authorization-code scopes below are advertised at inbox.lovedone.app/.well-known/oauth-authorization-server.


        Tools and required scopes:

        - ping — no scope

        - get_user_profile — profile:read

        - list_loved_ones — care_circle:read

        - list_care_events — care_circle:read

        - invite_family_member — care_circle:write

        - create_provider_code — care_circle:write

        - reply_to_inbox_message — care_circle:write


        Alias: POST https://inbox.lovedone.app/api/mcp'
      security:
      - LovedOneApiKey: []
      - LovedOneOAuth:
        - profile:read
        - care_circle:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                id: {}
                method:
                  type: string
                  enum:
                  - initialize
                  - tools/list
                  - tools/call
                  - ping
                params:
                  type: object
      responses:
        '200':
          description: JSON-RPC result
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or invalid credentials. WWW-Authenticate points at RFC 9728 resource metadata.
          headers:
            WWW-Authenticate:
              schema:
                type: string
components:
  securitySchemes:
    LovedOneApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-sand-
      description: 'LovedOne MCP API key minted by a signed-in family member at https://inbox.lovedone.app/settings/mcp-keys. Send `Authorization: Bearer sk-sand-...`. Phase 1 keys store a reserved `scopes` array; an empty list means full access for that caller (not anonymous public access). Keys never grant another family''s workspace.'
    LovedOneOAuth:
      type: oauth2
      description: 'OAuth 2.1 authorization-code + PKCE for MCP clients. Issuer https://inbox.lovedone.app. Metadata: https://inbox.lovedone.app/.well-known/oauth-authorization-server and https://inbox.lovedone.app/.well-known/oauth-protected-resource. Public scopes match packages/auth MCP_SCOPES (profile:read, care_circle:read, care_circle:write). audit:read exists in the schema but is not offered by default (public: false).'
      flows:
        authorizationCode:
          authorizationUrl: https://inbox.lovedone.app/oauth/authorize
          tokenUrl: https://inbox.lovedone.app/oauth/token
          refreshUrl: https://inbox.lovedone.app/oauth/token
          scopes:
            profile:read: See the caller's name, email, and LovedOne workspace membership. Required by get_user_profile.
            care_circle:read: List loved ones and read recent care events. Required by list_loved_ones and list_care_events.
            care_circle:write: Invite family, add providers, send replies, and add notes or visits on your behalf. Required by invite_family_member, create_provider_code, reply_to_inbox_message, add_visit_note, and schedule_visit.
            audit:read: Read the caller's agent activity log (internal — not advertised on the authorization server by default).