MCP server
Fellesly speaks the Model Context Protocol, so AI agents such as Claude, Codex and other MCP clients can read your family's plans and, if you allow it, make changes.
- Address: your API address plus
/v1/mcp, e.g.https://api.fellesly.no/v1/mcp - Transport: Streamable HTTP (JSON responses, no server-sent stream)
- Auth: a personal access token in
Authorization: Bearer fly_…
Ask things like "what's on this week?", "who picks up Emma on Thursday?", or, with a write token, "put taco ingredients on the shopping list" and "remind me about the dentist on Monday at 8".
Tools
| Tool | What it does | Needs |
|---|---|---|
list_families | Your families, with your member id and role in each | read |
today | The daily briefing: events, pickups, the meal, routines, open to-dos | read |
read | One kind of family data: events, lists, list items, routines, meals, recipes, reminders, places, contacts, messages, budget, the week plan… | read |
describe_action | The body schema of a change, so the agent fills it in correctly | read |
run_action | Create, update or delete family data (the same actions as the API) | write |
run_action is marked destructive, so most clients ask before running it.
What the agent can see and do
The agent acts as you, through the same checks as the app and the public API:
- Only families you are in (or just the one the token is bound to).
- Only what your role and visibility allow. A Read member's agent cannot change anything.
- With a read token,
run_actionalways fails. - Never your assistant chats or memories, live location, calendar share links, account settings, tokens, or family administration.
Least privilege
Start with a read-only token bound to one family. Switch to a write token only when you want the agent to make changes, and revoke it from More → Developer access when you're done.
Your data goes to the agent's provider
Whatever the agent reads is sent to the company running that agent (Anthropic, OpenAI, …), under your agreement with them. Other family members' events and lists may be part of that. Agree with your family before connecting an agent, the same as for the in-app assistant with your own key.
Protocol details
POST /v1/mcptakes one JSON-RPC message and answers with JSON. Notifications get202.GETandDELETEanswer405: there is no server-initiated stream and no session to end.- Supported protocol versions:
2025-06-18,2025-03-26,2024-11-05. - Each tool call counts toward the token's rate limit (an MCP call that reads data counts twice: once for the MCP request, once for the read).
Send Accept: application/json, text/event-stream on POST. Include the negotiated Mcp-Protocol-Version on subsequent requests; unsupported versions return 400. For older clients, a missing version header is accepted as 2025-03-26. No session ID is issued. GET returning 405 is the protocol's supported no-stream behavior. Valid JSON-RPC response messages also receive an empty 202. If Origin is present, it must exactly match the configured CORS_ORIGIN; other origins receive 403 on every method.
Use read's query object for limit, cursor and q. When another page exists, the tool returns { "items": [...], "nextCursor": "..." }; the final page is an array. Use the same resource, parameters and filters for continuation. run_action accepts an optional requestKey for POST retry protection using the public API's reservation semantics. Oversized tool results return a tool error rather than silently truncated JSON.
The API test suite connects the official TypeScript MCP client over a local HTTP socket and checks discovery, action descriptions, writes, request-key conflicts, pagination and token revocation. Deployment and interoperability with real Claude/Codex clients remain release acceptance checks.