Agents and MCP

The assistant inside the app has no private door. It works the product through a set of tools, and an agent you connect yourself gets the same set: boards and cards, notes, money, the kitchen, the family suite and the rest. The only tools held back from outside agents are web search and delegation, because both run our own models.

Connect a client#

The server lives at https://mcp.themarginapp.com/mcp and speaks MCP over Streamable HTTP. Settings→Integrations shows the address with a Copy button, which is all an assistant that takes custom connectors needs. There are two ways in.

• OAuth 2.1, with PKCE and dynamic client registration. A client that supports it finds everything from https://themarginapp.com/.well-known/oauth-authorization-server, opens a browser for you to sign in, and asks which workspaces it may use.
• A personal access token, made in Settings→Integrations and sent as a bearer. Simpler for scripts and for anything that cannot open a browser. You can hold several, each named, and revoke any of them there.

A client that reads a JSON config takes the token like this:

{
  "mcpServers": {
    "margin": {
      "url": "https://mcp.themarginapp.com/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}

When an assistant connects you approve it on The Margin's own page, Authorize access. It lists the workspaces you chose and says plainly what the assistant can do there: read what is in them, and add, change and delete things in them. It can act only in those workspaces. It also shows the website you go to after you approve, such as claude.ai or chatgpt.com. An app The Margin does not recognize is marked "Not verified by The Margin", and a name like "Claude" or "ChatGPT" only appears when the app really sends you back to that company's site; otherwise you see the website instead. Press Allow access to connect it. To end that access later, press End access beside it under Connected apps in Settings→Integrations.

Either way, the credential belongs to one person and holds one or more of their workspaces. A call may name any workspace the credential holds. Name one it does not and the refusal lists the ones it does, and nothing is quietly swapped for your default.

A new connection starts in the workspace it was made from, usually your personal one, while the shopping list, chores and meals live in a family workspace. So when you ask an assistant to add something to the list and it has not said which workspace, The Margin looks at the workspaces you granted. If exactly one of them has the feature, a request that only reads, or that adds something plain (an item on the list, a meal, a chore, a calendar event, a recipe, a note, a card), runs there and the answer says which workspace it used. Anything heavier is never sent somewhere you did not name: deleting or editing, moving points or money, adding or assigning a person, changing settings, approving a chore. For those, and whenever two workspaces could take the request, the assistant is told which workspaces have the feature and asks you. Your active workspace stays where it was until you ask the assistant to switch.

Every call is checked against workspace membership, so an agent cannot reach a workspace you are not in. That holds after the connection is made too: when someone is removed from a workspace, their assistant loses it on its next call, without anyone revoking anything. Apps you have approved over OAuth are listed in Settings→Integrations, where you can cut one off.

Let an agent try it with no account#

An agent can try the whole surface before anyone signs up. Connect any MCP client to https://mcp.themarginapp.com/sandbox/mcp with no credential, and the server makes a sandbox for that connection: a made-up household (Alex Rivera, their partner Sam, the kids Maya and Leo, and Biscuit the dog) across a personal and a family workspace, with boards, notes, habits, money, chores, recipes and a week of meals already in it. The agent acts as Alex, and every tool does what it does for real.

With Claude Code:

claude mcp add --transport http margin-sandbox https://mcp.themarginapp.com/sandbox/mcp

With Cursor, or any client that reads a JSON config (no headers needed):

{
  "mcpServers": {
    "margin-sandbox": { "url": "https://mcp.themarginapp.com/sandbox/mcp" }
  }
}

A web chat that takes custom connectors needs only the address, with no authentication. A client that also speaks the older revisions of MCP (Claude Code and Cursor do) is steered to the initialize handshake, which makes the sandbox, so the one line above is all it takes. A client that speaks only the stateless 2026-07-28 revision has no session to hang a sandbox on, so it asks for one first and sends the access_token from the answer as a bearer on every request:

curl -X POST https://mcp.themarginapp.com/sandbox/session

On the first call, and then every fifth, a successful result ends with one more line for the person the agent is helping: a link to try The Margin in their own browser and keep a real workspace. It is its own text block after the result, so a JSON answer still parses, and it never rides on a refusal.

What is off in the sandbox#

A sandbox does not fail on what it leaves out: it says so. A tool that is off answers with the error not_in_sandbox, a message naming the limit and why, the limit it falls under, and unlocked_by, which is an account. Everything not listed here works for real.

Pacts can still be read. Nobody can be emailed or notified from a sandbox. A sandbox cannot see a real workspace, and no real account can see a sandbox. The same list, as data, is at https://mcp.themarginapp.com/sandbox under off_in_the_sandbox.

The live figures, and the connect details, are at https://mcp.themarginapp.com/sandbox. A client that closes its MCP session ends its sandbox straight away. When the agent has seen enough, the next step belongs to the person: sign up, and their own workspace starts empty and private.

What the tools cover#

Boards and cards, notes and folders, checklists and templates, habits and focus sessions, expenses, budgets, income and debts, chat, whiteboards and Canva designs, recipes, the weekly meal plan and the shopping list, the family suite, the Team Hub, Agent Pacts, the Mind, and sharing and connections.

get_week_overview answers "what does my week look like" in one read across every workspace the connection was granted: tasks due, events, meals, chores with whose turn it is, shopping lists, and the person's own habits and journal lines. The active workspace comes back whole and every other one as the person's own rows plus one summary line; detail: "full" lists everything. Each row names its source, and times are in 12-hour form. It only reads. Its scope is the workspaces you granted when you connected the assistant, narrowed by the in-app Answer from setting: with This workspace it reads only the workspace the connection is working in, and All my workspaces never reaches past what you granted. The answer's scope field says which applied.

About you is the person's own memory, kept apart from every workspace: facts about them, such as how they like answers, that only they can see. list_about_me reads it, add_about_me_fact keeps a new fact when the person asks you to remember something about themselves, and update_about_me_fact and forget_about_me_fact change one by its id. Every call acts for the person who connected, and nobody else.

For a team, list_workspace_members and get_team_workload answer who is on it and who is carrying what. Owners and admins also get three reads from the Team Hub's admin console: get_team_activity (the audit trail, newest first, a page at a time), get_board_access (who can open which board) and get_team_seats (seats bought and held, and this month's assistant use for the team and each person). On a Team workspace they also get list_security_events: the security log, with sign-ins, two-factor changes, role and access changes, sharing, policies and exports, newest first. It can be narrowed to one kind of entry or one person, and every answer says whether the log's hash chain still checks out. They only read; changing people, access or seats stays in the app. See Team hub.

search_help and get_help_article read these docs. Ask a connected assistant how something in The Margin works and it can find the page, quote the part that answers you and give you the link, instead of guessing. They read no workspace data and work on every plan, Free included.

The server also offers resources. margin://guide holds the rules that hold on every tool, and margin://guide/<domain> has one page per area (boards, notes, money, family, the kitchen, pacts and so on), each with the loop, the traps and a worked example. The server's instructions tell a connecting agent it is there. There are workspace summaries for orientation, and prompts for common jobs.

A resource the connection may not read, such as a pact it has no seat in or a workspace its token was not granted, is answered with MCP's resource-not-found error (-32002) and the address in data.uri. The message is the same sentence the matching tool gives, so an agent can tell a wrong workspace from a missing seat.

Hand over a whole task#

MCP is the tool plane. A2A is the other one: rather than calling forty tools, an outside agent hands a task to one of Margin's specialist agents and collects the result.

The endpoint is https://themarginapp.com/api/a2a. It takes a POST authorized with the same OAuth bearer, and a GET on the same address describes it. The agent card at https://themarginapp.com/.well-known/agent-card.json lists the skills that really run:

• Create a plan, or refine one when something slips.
• Research a topic, analyze a document, compare options.
• Triage one inbox capture, or the whole inbox in one pass.

A long task can be queued and collected later by job id. Every skill on the card is one the gateway accepts, because a skill that is refused only after someone has built against it is worse than no card.

Several agents in one workspace#

When more than one agent works in your workspace, Agent Pacts is where they work together: one shared page per job, one zone each, a thread nobody can rewrite, and every question they cannot settle sent to you.

Permission hints on every tool#

Every tool says what it may do, in the standard MCP annotations, so a client can decide what to run without asking and what to check with you first.

• A title in plain words, such as "Add Shopping Item". It is sent once: as the tool's title to clients on protocol 2025-06-18 or later, and as annotations.title to older ones.
• readOnlyHint on the tools that only read: every list, get and search. Two of them leave a receipt. get_card and get_board_snapshot add a "seen by agent" entry to the board's activity feed, so you can tell a request was read. It is written at most once an hour for each card or board, and nothing you wrote changes.
• destructiveHint on the tools that delete something or replace what was there: every delete and remove, every update, and the few tools with a replace or clear option, such as plan_week and add_whiteboard_elements. It is also on tools that replace what was there when you call them a second time: share_resource changes the role of someone who already has access, and create_allowance_pool replaces the allowance a child already has.
• destructiveHint: false on the tools that only add, such as create_card, add_shopping_item and append_to_note.
• openWorldHint: false on everything that works only on your own data. The five tools that reach outside The Margin leave it out, which the protocol reads as open world: search_recipe_catalog, import_recipe_from_url, refresh_exchange_rates, import_canva_design and upload_attachment when it is given a URL.

A hint is left out when leaving it out means the same thing, to keep the tool list small: readOnlyHint on a tool that writes, idempotentHint unless it is true, and the write hints on a tool that only reads.

Who wrote something is never an argument. The author of a card, note or chore, who approved a chore and who acted are taken from your sign-in, so no tool lists created_by or the like. A client that still sends one is not refused for it and your sign-in is used instead, except that naming someone else as a chore's approver is refused.

The money tools record amounts. settle_balance, record_debt_payment, contribute_to_savings_goal, record_ledger_entry and the allowance tools write down what was paid or what is owed. None of them sends, charges or moves money.

No tool reads the connected assistant's own memory or chat history. A tool receives the arguments of that one call and nothing else.

Five lists that grow with use take limit and offset. list_debts and list_hidden return 200 rows by default and at most 500, and the answer says what it left out: count is the total, returned is the size of this page, and has_more with next_offset tell you whether to ask again. list_habits, list_templates and list_attachments return a plain list of up to 1,000 rows, which is more than any plan's count limit, so an answer that was complete before is still complete.

When a call fails, the answer says what to change: the argument you left out by name, the format an id or date should have, or that the fault is on our side. It says "Nothing was saved" only when that is certain, which is when the tool makes its changes in one step that either all happens or does not happen at all. Every tool that writes more than one thing now works that way, such as splitting an expense, approving a chore or sharing an item. For the few that cannot, such as a Canva import that fetches the cover after saving the design, the answer tells you to read the item back before trying again.

Conventions for whoever writes the agent#

When an agent's changes show up#

An agent writes to the server's copy, and your devices pick the change up on their next sync, which is usually straight away. An open whiteboard is the exception: it takes outside changes when you reopen it. See Working offline.

Who added what#

Ask Claude, ChatGPT or Grok to add cat litter to the list and you get the same row each time. The text never says which assistant wrote it. Anything an assistant adds carries a small mark in its details instead, the same mark whichever one did it. Hover over the mark, or tap it on a phone, and it tells you who asked and through what: "Added by Alex through Claude". Things the built-in assistant adds say "through Margin Intelligence".

The mark shows on shopping items, notes, cards, checklists, chores, calendar events, meal plans, recipes, expenses, income, comments and chat messages. A whiteboard shows it on its tile in the list, never on the canvas.

Each connection takes its name from what the app called itself when it connected, shortened to the product: Claude, ChatGPT, Grok, Cursor. Rename it in Settings→Integrations→Connected apps, say "Work Claude" and "Home Claude", and the new name reaches everything it already added in the workspaces you are still in. A token you mint in Settings keeps the name you gave it, and shows in the same list. End a connection and its items keep the last name it had.

The phone app has the same list in Settings→Connections→Connected apps, where you can rename a connection or end its access. Generate access token there makes a personal access token for the workspace you are in, named for the client it is for. It is shown once, with a button to share or copy it, and then appears in the list like any other. Connecting an assistant by sign-in still starts from that assistant's own app, through the browser.

Why an assistant changed something#

An assistant can say why it made a change, and the mark shows that too: "Added by Alex through Claude: to keep the grocery run under budget". Open the mark on a shopping item, card, note, checklist item, calendar event, expense, income entry or chore. When the last thing an assistant did was an edit or a move, the sentence says so ("Edited by Alex through Claude: two bags, not one").

Every connected assistant is asked to give a reason with each change, and Margin Intelligence always does. The same lines appear in the workspace's activity feed, so you can read back what assistants changed and why. A private expense or income entry stays private: the mark still says who added it, and the reason is not kept anywhere others could read it.

For whoever writes the agent: these tools take an optional reason, one line of up to 280 characters (longer is shortened, never refused): create_card, update_card, move_card, create_note, update_note, append_to_note, add_checklist_item, update_checklist_item, add_shopping_item, update_shopping_item, create_family_event, update_family_event, create_expense, update_expense, create_income, create_chore and update_chore.

Notes for assistants#

Tell every assistant how things are done in your workspace once, instead of repeating it in each chat. Open Settings→Workspace and write a few plain sentences under Notes for assistants, for example:

• Groceries go on the Family list, not on a board.
• Ask before deleting anything.
• Money entries are in US dollars unless someone says otherwise.

Every assistant reads them before it works: Margin Intelligence on every turn, and Claude, ChatGPT or Cursor in the instructions they get when they connect. A board can have notes of its own in its settings (the board's menu, then Board settings), read after the workspace's whenever an assistant works on that board. Up to 2,000 characters each.

Owners and admins write the workspace's notes. A board's notes belong to its owner, or to a workspace owner or admin. Everyone else in the workspace can read them, on the web and in the phone app (Settings→Workspace, and a board's Fields and rules sheet).

Picking up where another assistant stopped#

list_assistant_activity returns what assistants changed in the workspace lately, newest first: when, for whom, which assistant, what it did to which item, and the reason it gave. Pass a board_id to see one board. A second assistant reads it to carry on where the first one stopped, and anyone can ask "why did this change?" and get the answer from it. get_assistant_notes reads the notes above. Both are on every plan, and both see only the boards the person can see. For two agents working on the same job at the same time, use Agent Pacts.

What agents cannot reach#

No agent session can unlock the Vault. A note, card, board, whiteboard or checklist sealed in anyone's Vault is answered as not found by every tool: it never appears in a list, a search, a count or a board, even while its owner has the Vault open. A PIN-locked note gives an agent its existence and nothing more: no body, and it matches a search on its title only. Anything you mark Hide from memory stays out of what the Mind recalls for an agent, exactly as it does for the built-in assistant, though the note itself is still a note an agent in that workspace can list. The Vault hides; it is not end-to-end encryption, and Your data says exactly what it does and does not do. See also Curating the Mind.

How to check the Vault yourself#

You don't have to take that on trust. Every sandbox comes with Alex's Vault set up in the family workspace, the one a call uses when it names none. It holds one of each thing a Vault can seal, all about a surprise for Sam's birthday, and next to each sits an unsealed twin with a similar title:

vault_status answers configured: true with five items. Then try to find them: search_notes and search_cards for "Sam", list_notes, list_boards, get_cards, list_whiteboards and list_checklists, get_board_summary on the Home board, and the resource workspace://<workspace_id>/today. Every twin should show up and nothing sealed should, not even the card on the sealed board. Nobody can unlock this Vault, so it stays that way for the life of the sandbox. If a sealed title ever shows up in an answer, that is a bug, and we want to hear about it at hello@themarginapp.com.

Availability#

The machine-readable entry points need no account: /llms.txt, /llms-full.txt, the server card, the agent card, the OAuth discovery documents, and the sandbox above, which is how an agent tries the paid surface without anyone paying.