# Agents and MCP > Point any MCP client at your workspace and give it the same tools the built-in assistant uses, let an agent try it on a demo household with no account, or hand a whole task to a specialist agent over A2A. 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: ```json { "mcpServers": { "margin": { "url": "https://mcp.themarginapp.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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. > **Tip: Look before you connect** `https://themarginapp.com/.well-known/mcp/server-card.json` reports the live > tool count, the transport and the sign-in endpoints. It is generated from the > server, so it stays current between releases. ## 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: ```bash 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): ```json { "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: ```bash 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. | Off in the sandbox | What it is | Why | With an account | Tools that answer `not_in_sandbox` | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent Pacts | A pact is a lasting record two agents keep about work they share. | A pact is permanent and a sandbox is deleted within hours, so pacts can be read here but not written. | Agent Pacts come with Pro, Family and Team. | `create_pact`, `invite_to_pact`, `join_pact`, `post_pact_message`, `update_pact_section`, `raise_pact_decision`, `update_pact_handshake`, `set_pact_delivery` | | Sharing and invitations | Sharing an item, inviting someone or sending a connection request. | Each of these reaches a real person's account, and nobody real is on the other side of a sandbox. | A free account can invite one person into its workspace, and the shopping list is on every plan. Sharing a board or a single item with a guest comes with Family and Team. | `share_resource`, `send_connection_request` | | Outside services | Canva, Google Calendar and Sheets, web recipe import, the recipe catalog and live exchange rates. | They call a service outside The Margin, and a sandbox makes no outbound requests. | Web recipe import, the recipe catalog and exchange rates work on every plan, Free included. Canva and Google Calendar and Sheets come with Pro, Family and Team. | `import_canva_design`, `embed_canva_design`, `search_canva_designs`, `import_recipe_from_url`, `search_recipe_catalog`, `refresh_exchange_rates` | | File uploads | Attaching a file or rendering a whiteboard to an image. | Both write to file storage, which is off in the sandbox. | Attachments and whiteboard images work on every plan, Free included, with more storage on the paid plans. | `upload_attachment`, `export_whiteboard_png` | | Memory | The Mind and the Weave: what The Margin remembers and the connections it suggests. | Memory is built from an account's own history over time, and a sandbox has none to build from. The review queue can be read here, and it is empty. | Memory builds from your own notes and cards on every plan, Free included. Writing to it from an outside assistant comes with Pro, Family and Team. | `learn_from_interaction`, `store_family_preference`, `accept_suggestion` | | Full Margin Intelligence and agents | Voice dictation, team agents and every tool that asks a model to do work. The assistant is here in a small form: it reads a summary of the sandbox, answers up to ten questions, and cannot change anything. | They run a model on an account's allowance, and a sandbox has no account. | Margin Intelligence and voice dictation work on every plan, with a smaller monthly allowance on Free. Team agents come with Team. | None: not a tool | | Account and billing | Plans, billing, connected apps, notifications to your devices and email. | They belong to an account, and a sandbox has none. | Every account has these, Free included. | None: not a tool | 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`. | Sandbox limit | Default | | ------------------------------ | ----------------------------------- | | Idle time before it is deleted | 1 hour after the last call | | Longest life | 3 hours, however busy | | Calls | 60 a minute, 1,500 in all | | Changes | 400 (reads keep working after that) | | Rows per table | 200 | | Live sandboxes per address | 3 | 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](https://themarginapp.com/docs/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. > **For agents: Two families stay inside** Web search and delegation to Margin's own specialist agents are not offered > over MCP. Both run our models against our budget, and a connected client > brings its own. Listing them would only advertise a refusal. The server also offers resources. `margin://guide` holds the rules that hold on every tool, and `margin://guide/` 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](https://themarginapp.com/docs/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 > **For agents: Working rules** > > - Identifiers are UUIDs. Tools take and return JSON. A name or a placeholder > where an id belongs, or a date not in ISO 8601, is refused before anything > runs, with the argument named and the form it expects. > - An argument a tool does not take is refused, never ignored. The answer > names it and lists the arguments the tool does take, and when you sent a > name where an id belongs (`category` for `category_id`) it says which to > send. Nothing is written. > - A refusal is a tool result with `isError` set, in plain words you can act > on: a workspace the connection may not act in, a person outside the > workspace, a plan that lacks the feature. Protocol errors are kept for > malformed requests and tools that do not exist (an unknown tool is > `-32602`, as the MCP spec shows it). > - When the connection itself no longer works, because the person has left > every workspace it was granted or its token was revoked, the answer is HTTP > 401 with a `WWW-Authenticate` header that points at sign-in. Connect again. > - One session runs four calls at a time and queues a few dozen more. Past > that, or after a ten-second wait, the call is answered with HTTP 429 and a > `Retry-After`; wait and send it again. Parallel calls are fine, a flood is > not. > - Every response carries `Server-Timing` and `X-Response-Time` with the > server's own time in milliseconds, up to the first byte. Compare it with > your total time to see how much of a slow call was the network. > - If a session was opened in a workspace the account has since left, the > server ends it with a 404 and a message to reconnect. Starting a new > session picks up the workspaces the account reaches now. > - Card and column order uses fractional-index strings. Call `move_card` > rather than writing positions. > - Note content is markdown. Whiteboards are Excalidraw scenes. Note tags are > JSON arrays. > - Read tools are safe to call freely. Write tools change real data, and > anything marked `destructiveHint` should be confirmed with the person first. > - Read previews first. `search_notes` and `list_notes` return previews, and > deep reads use bulk fetches or offset paging. Ten single fetches cost more > than one bulk call, because each round sends the whole conversation again. ## 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](https://themarginapp.com/docs/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](https://themarginapp.com/docs/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](https://themarginapp.com/docs/your-data#the-vault) says exactly what it does and does not do. See also [Curating the Mind](https://themarginapp.com/docs/curating-the-mind). ### How to check the Vault yourself You don't have to take that on trust. Every [sandbox](#let-an-agent-try-it-with-no-account) 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: | Sealed in the Vault | Its unsealed twin | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | Note "Sam's birthday present" | Note "Sam's birthday menu" | | Card "Pick up Sam's birthday watch", on the Home board | Card "Pick up Sam's birthday cake", same board and column | | Board "Sam's surprise birthday party", with its card "Call the venue about Sam's birthday party" | Board "Sam's birthday weekend" | | Whiteboard "Sam's surprise party floor plan" | Whiteboard "Sam's birthday dinner seating" | | Checklist "Sam's surprise party shopping" | Checklist "Sam's birthday dinner shopping" | `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:///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 . ## Availability > **Known limit: Pro and up** Connecting an outside agent, over MCP or A2A, is part of Pro, Family and > Team, and of any running trial. A Free workspace refuses the connection with a > sentence saying so. 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. **Where to next** - [Agent Pacts](https://themarginapp.com/docs/agent-pacts): several agents on one job, with rules the server enforces - [Margin Intelligence](https://themarginapp.com/docs/margin-ai): the assistant that uses the same tools inside the app - [Integrations](https://themarginapp.com/docs/integrations): webhooks, Google and Canva --- Section: Control and connections. Checked against the running product on October 8, 2026. Web page: https://themarginapp.com/docs/agents-and-mcp. Every docs page: https://themarginapp.com/docs/llms.txt