01 · OVERVIEW
What this connector does
FamilyWell is a shared organizer for the people you live with: to-dos, shopping, calendar, spending, recipes, inventory, cars, contacts and more. This is FamilyWell's remote MCP server. Your assistant calls it to read and change one family's data on your behalf, under the same sharing rules and validation as the FamilyWell app.
- Ask what's on today across tasks, events, birthdays and car services, in one answer.
- Add to a shopping list, log an expense, plan a car service or save a recipe from a chat.
- Use interactive widgets in clients that support MCP Apps: tick tasks, scale a recipe, browse spending by category.
The assistant only acts when you ask it to, and only as you. It never sees other families, your password or payment details, and it has no access until you approve a connection.
02 · REQUIREMENTS
What you need
- A FamilyWell account at familywell.co, and membership of at least one family. Self-hosted installs use their own address,
https://<your host>/mcp. - An MCP client that supports remote servers over Streamable HTTP with OAuth, such as Claude, ChatGPT, Claude Code, Cursor, VS Code (Copilot), Codex or Gemini CLI.
- On business plans (for example Claude Team or Enterprise, ChatGPT Business or Enterprise) a workspace admin may need to add or allow FamilyWell first. Each member then connects their own account.
03 · SET UP
Connect your assistant
Every client follows the same three steps. Only where you paste the address changes.
- 1Add a remote MCP serverPaste
https://mcp.familywell.co/mcp. No API key or token: the client finds the sign-in from the address. Self-hosted:https://<your host>/mcp. - 2Sign in to FamilyWellThe client opens a browser window on familywell.co. Sign in if you aren't already.
- 3Choose a family and permissionsPick exactly one family, then No access, Read, or Read & write for each module. Every module starts at No access. Click Allow and you're back in your assistant.
Where to add it
Customize → Connectors → Add custom connector. Paste the address, press Add, then Connect.
Plugins → Add → Create plugin. Paste the address and leave Authentication on OAuth.
Run once, then /mcp → familywell → Authenticate.claude mcp add --transport http familywell https://mcp.familywell.co/mcp
Cursor Settings → Tools & MCP → New MCP server, then Connect."familywell": { "url": "https://mcp.familywell.co/mcp" }
Command Palette → MCP: Add Server → HTTP. Start it and allow the sign-in. Use it from Copilot's agent mode.
Add, then sign in.codex mcp add familywell --url https://mcp.familywell.co/mcpcodex mcp login familywell
Add, then run /mcp auth familywell inside Gemini CLI.gemini mcp add --transport http familywell https://mcp.familywell.co/mcp
Look for “custom connector”, “remote server” or “Streamable HTTP”.
Every connection shows the consent screen, even for an assistant you've connected before, so each one carries its own family and permissions.
04 · EXAMPLES
Things to ask
Each example lists the tools the assistant calls and the access the connection needs. Yellow tools change data.
“What's on for us today?”
Shows the Today widget with due tasks, events, birthdays and car services. You can tick items off right in the chat.
get_today
“Add milk, eggs and two lemons to the Lidl list.”
Finds the list by name and adds three items, grouped by aisle.
shopping_list_listsshopping_add_item
“Scale Grandma's pancakes to 8 people and add what we're missing to shopping.”
Scales every ingredient, checks the pantry, and adds only what's short.
recipes_scaleinventory_listrecipes_add_to_shopping
“The Golf is at 48,200 km. When is its next service due?”
Logs the odometer reading, then reports the next due service by distance or date.
vehicles_log_mileagevehicles_get
05 · AUTHENTICATION
How sign-in works
FamilyWell uses standard OAuth 2.1 with the authorization code flow and PKCE. There are no API keys or personal tokens to copy, store or leak. Clients register themselves through dynamic client registration (RFC 7591) and find the endpoints through the published discovery documents. Desktop clients can use private-use redirect schemes (RFC 8252).
| ENDPOINT | PURPOSE |
|---|---|
| /.well-known/oauth-protected-resource | Resource metadata (RFC 9728), points to the authorization server |
| /.well-known/oauth-authorization-server | Authorization server metadata (RFC 8414) |
| POST /oauth/register | Dynamic client registration, rate limited |
| /oauth/authorize | Sign-in and consent screen on familywell.co |
| POST /oauth/token | Issues and refreshes tokens |
| POST /mcp | The MCP server, bearer token required |
Access tokens last 1 hour and refresh tokens 30 days. A connection that isn't used for 30 days expires and has to be reconnected. Tokens are signed with an RSA key pair held only by FamilyWell.
06 · PERMISSIONS
What the assistant can reach
You decide on FamilyWell's consent screen, not in the assistant. Whatever scopes the client asks for are ignored. The token carries exactly what you allowed:
| SCOPE | MEANING |
|---|---|
| mcp:use | May call the MCP server at all |
| family:<id> | Bound to exactly one family. Membership is re-checked on every call. |
| <module>:read | May use that module's read tools |
| <module>:write | May also create, change and delete in that module |
- Tools you didn't allow don't exist.
- A module set to No access is never listed to the client, so its tools can't be called.
- It acts as you.
- The same sharing rules apply as in the app: another member's private list stays invisible, and the family gets the same notifications.
- Family name and members are always visible.
- get_family and get_today are included with every connection so the assistant knows who's who.
- Modules turned on later need a reconnect.
- Permissions are fixed when you click Allow. The assistant is told to ask you to reconnect if a new module is missing.
07 · DATA & PRIVACY
What data moves, and where it lives
The server only returns data from the one family and the modules you approved. Everything below is covered in full by the FamilyWell privacy policy.
- Data the client can read
- The approved modules' content for that family (for example list items, events, expenses, recipes, car records) plus the family's name and members. Never passwords, payment details, or data from other families you belong to.
- Where it's stored
- FamilyWell's database runs on DigitalOcean in Frankfurt, Germany. Uploaded files sit in private storage and are only served to members of their family. All traffic uses TLS.
- What we keep about a connection
- The client's name, the family, the permissions you granted and its tokens. Deleted when you disconnect or delete your account.
- Your AI provider
- Whatever the assistant reads, and what you ask it, is processed by that assistant's provider (for example Anthropic or OpenAI) under its own terms. The provider is a service you chose, not FamilyWell's processor.
- Deletes
- Tasks, lists, shopping items, expenses, notes and calendar events go to a 30-day trash and can be restored. Contacts, birthdays, inventory items, projects and car records are deleted permanently: those tools are marked destructive so clients ask before running them.
- Advertising
- FamilyWell doesn't sell personal data, run ad pixels or build ad profiles.
- Legal basis
- Consent, withdrawn by disconnecting. FamilyWell is operated from Romania (EU) under the GDPR. Data requests: hello@familywell.org.
08 · REVOKING ACCESS
Disconnecting an assistant
- In FamilyWell
- Settings → Connected apps → Disconnect. Its tokens stop working immediately. This page also shows each connection's family and permissions.
- Leaving a family
- Cuts off every connection made for that family, automatically.
- In the assistant
- Removing the connector stops the client from calling FamilyWell. Disconnect in FamilyWell too, so its tokens are revoked on our side.
- Unused connections
- Expire after 30 days without use.
09 · TOOLS
98 tools across 12 groups
A connection only lists the tools of modules the family has turned on and you allowed. Read tools carry the read-only hint; permanent deletes carry the destructive hint. In clients that support MCP Apps, read tools also show an interactive widget.
| MODULE | READ | WRITE (NEEDS READ & WRITE) |
|---|---|---|
| Core | get_family, get_today | — |
| Tasks | tasks_list_lists, tasks_get_list, tasks_search | create / update / delete list and task, list_deleted, restore |
| Shopping | shopping_list_lists, shopping_get_list, shopping_search | create / update / delete list, add / update / delete item, list_deleted, restore |
| Calendar | calendar_list, calendar_get_event | create / update / delete event, add / update / delete to-do, list_deleted, restore |
| Spending | spending_list_expenses, spending_get_expense, spending_summary, spending_list_categories | add / update / delete expense, list_deleted, restore |
| Notes | notes_list, notes_get, notes_search | create, update, delete, list_deleted, restore |
| Recipes | recipes_list, recipes_get, recipes_scale | create, update, set_photo, add_to_shopping, delete |
| Inventory | inventory_list, inventory_get, inventory_needs_attention | add / update item, adjust_quantity, add_to_shopping, delete_item |
| Vehicles | vehicles_list, vehicles_get, vehicles_history | log_mileage, log_fuel, add / update / complete maintenance, add_repair, add_expense, add_document, attach_file, delete_record, delete |
| Projects | projects_list, projects_get | create, update, add / update / delete task, delete |
| Contacts | contacts_list, contacts_get | create, update, delete |
| Birthdays | birthdays_list | add, update, delete |
Write tool names are prefixed with the module, e.g. shopping_add_item. Recipes add_to_shopping also needs Read & write on Shopping.
10 · LIMITS
Limits and known gaps
- 120 / min
- Tool calls per token. Over the limit returns HTTP 429; wait a minute.
- 12 MB
- Per file: PDF, JPEG, PNG, WebP or HEIC, sent as a file reference, a public https URL or base64. Private network addresses are refused.
- 400 days
- Longest date range for one calendar_list call.
- Kilometres
- Vehicle distances go in and out in km. Miles are a display setting only.
- Not yet
- Personal access tokens, MCP resources and prompts, splitting costs and receipts over MCP.
11 · TROUBLESHOOTING
If something's off
- A module I turned on is missing.
- Permissions are fixed when you click Allow. Disconnect and connect again, and allow the new module.
- The client says it needs to log in again.
- The connection was disconnected, you left the family, or it went unused for 30 days. Connect again.
- It can't see a list I know exists.
- It sees what you see in the app. Another member's private list stays private.
- A widget says it needs Read & write.
- The connection has Read access for that module. Reconnect with Read & write to change things from the widget.
- It can't attach a file from my chat.
- Some clients can't pass chat attachments. The assistant creates the record and links you to the page in FamilyWell to upload it.
12 · SUPPORT