Skip to content
Kin

For developers

Work with a family's circle. Never approve.

A family member's own AI assistant connects to Kin's MCP server by signing in through OAuth, or with a token the member grants. A home-care agency's software reports visits through a signed API. Both read and propose; a person in Kin approves.

MCP server

Connect an assistant

Streamable HTTP, one JSON-RPC message per request, no session. Protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. A client signs in through OAuth 2.1, or the member creates a token on the Connected assistants screen.

Endpoint
https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp

Sign in from your client

Add Kin's address with no token. Your client finds Kin from the 401, registers, and opens Kin in your browser; you sign in, choose what it may do and for how long, and say yes. Kin is its own OAuth 2.1 authorization server: PKCE with S256, client ID metadata documents or dynamic registration, the resource indicator, and no refresh token.

Claude Code, signing in
claude mcp add --transport http kin https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp
Authorization server metadata
https://mzdg4f3stk.us-east-1.awsapprunner.com/.well-known/oauth-authorization-server
Claude Code, with a token
claude mcp add --transport http kin https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp --header "Authorization: Bearer <your-delegation-token>"
MCP client settings (.mcp.json)
{
  "mcpServers": {
    "kin": {
      "type": "http",
      "url": "https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-delegation-token>"
      }
    }
  }
}
Any HTTP client
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp \
  -H "Authorization: Bearer <your-delegation-token>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The tools

The same tools and the same gateway as Ask Kin. tools/list shows only those the member's role and the token's scope allow.

  • get_poolReads

    The circle's pool: its confirmed balance now, this month's money paid in, paid out and PayPal fees, and what this month's spending went on by category (bills, receipts members paid from their own pocket, and purchases). Use it for any question about how much money there is, or how much was spent on something this month.

  • list_billsReads

    The circle's bills: those the family expects next, those waiting for approval, and those paid, with payee, amount and day. A caregiver sees only their own. It does not hold receipts or purchases: for what was spent on something, use get_pool.

  • get_fairnessReads

    This month's fairness, as Kin's money core calculates it: each sharing member's agreed share, what they gave, and who owes whom to settle. Use it for any question about shares, fairness or who owes whom.

  • check_claimReads

    Checks a demand for money against the record, with Kin's fixed rules: is the payee known, is there an open bill of that amount, was it already paid. It only reads; nobody is alerted. Use it when someone asks whether a demand, call or letter is real.

  • list_proposalsReads

    The payments waiting for a yes, and who still has to say yes to each, as the approval engine decided. Kin cannot answer for anyone.

  • get_recordReads

    The newest entries of the circle's ledger: what happened, to whom, how much and on which day, and whether it was simulated.

  • get_paypal_payout_statusReads

    Whether someone has been paid: the payouts the record holds for a payee or caregiver, and, for a real payout, its status read from PayPal now. Simulated payouts in a demo say so.

  • get_paypal_topup_statusReads

    The members' top-ups into the pool: amount, day and, for a real top-up, the status of its capture read from PayPal now. Simulated top-ups in a demo say so.

  • get_subscription_statusReads

    Each member's monthly share through PayPal subscriptions: its amount, its state and its next charge, read from PayPal for a real one. Simulated shares in a demo say so.

  • get_paypal_orderReads

    PayPal's own record of a top-up, read from PayPal now through the PayPal Agent Toolkit: the PayPal order behind the newest real top-up, its status, amount, times and capture. A simulated top-up has no PayPal record, and the result says so. Use it when someone asks what PayPal itself says about a top-up.

  • get_paypal_invoiceReads

    PayPal's own record of an invoice Kin sent a member, read from PayPal now through the PayPal Agent Toolkit: its number, status, amount and what was paid on it. A simulated invoice has no PayPal record, and the result says so. Use it when someone asks whether an invoice was paid or where it stands at PayPal.

  • list_paypal_disputesReads

    Whether anyone has disputed one of the circle's newest real top-ups with PayPal, read from PayPal now through the PayPal Agent Toolkit: each dispute's status, reason and amount. Use it when someone asks about a dispute, a chargeback or a payment someone says they did not make.

  • propose_refillProposes

    Asks Kin to propose a refill the family's rules already allow, at the rule's own price. It buys nothing: the refill then waits for the yeses the family agreement names, unless the parent's standing permission covers it. Use it only when the person asks for a reorder or refill.

  • propose_giftProposes

    For the parent only: asks Kin to send a small payment from her own Purse, such as a gift, a tip or a donation, to someone she names. It pays nothing: Kin reads the payment back and it waits for her own yes, and Kin's rules hold it for a day, with the family told, when the person is not in her address book, the amount is above her limit or the request looks pressured. Use it only when she asks to send, give or pay someone money from her Purse.

The boundary

What no outside caller can do

  • No tool approves, pays, signs or moves money. A tool that proposes returns the proposal's ID and the screen where a person approves it, and the proposal waits for that person even where the parent's standing permission would cover it.
  • PayPal's own tools, writes included, stay on Kin's server and are never offered here.
  • The token's scope only narrows the member's own role. Revoking it refuses the very next call.
  • Text from the record (names, notes, letters) comes back labelled as data, inside a tag it cannot close.
  • A request without a live token gets 401 and a WWW-Authenticate header that points at the protected resource metadata.

Agency API

Report a visit

POST one visit to /api/v1/visits, signed with the key the circle's organizer created. Kin keeps it as evidence beside the shift. It pays nothing.

Sign the raw body
BODY='{"externalId":"visit-1042","caregiver":"Caregiver","kind":"aide","startsAt":"2026-11-09T09:00:00-05:00","endsAt":"2026-11-09T13:00:00-05:00","checkedInAt":"2026-11-09T09:02:00-05:00","checkedOutAt":"2026-11-09T13:00:00-05:00"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/v1/visits \
  -H "Content-Type: application/json" \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

201 kept · 200 already kept · 401 key or signature · 409 same ID, other body · 422 kept but unreadable

Agency API

Send an invoice

POST an invoice to /api/v1/invoices, signed exactly like a visit. Each line names a visit the agency already reported, in integer cents; Kin adds the lines up itself. The invoice becomes a bill the family reviews against the visits it confirmed. It pays nothing by itself.

Sign and send an invoice
BODY='{"invoiceNumber":"INV-1042","periodStart":"2026-11-01","periodEnd":"2026-11-30","lines":[{"visitId":"visit-1042","minutes":240,"amountCents":11200,"currency":"USD"}],"totalCents":11200,"currency":"USD","dueOn":"2026-12-15","paypalEmail":"billing@agency.example"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG" \
  -d "$BODY"
Ask where it stands (sign the path)
P=/api/v1/invoices/INV-1042
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$P" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com$P \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG"

201 kept for review · 200 already kept · 401 key or signature · 409 same number, other body · 422 kept but refused, with why · GET: received, under_review, approved, paid, declined

OpenAPI

The published document

Built from the schemas the server checks requests against, so it cannot drift.

Open the OpenAPI document

SDKs for TypeScript and Python, generated by APIMatic from this same document. Each comes with a signed example for the agency API.

Start with one conversation with your family.