Keystone Developers
Open Keystone
Guides

MCP

How a session works

Find, open, snapshot, propose, apply: the life of an edit through the MCP server.

Reviewed Oct 10, 2026

The Keystone MCP server lets an assistant change a business's information without ever being able to change it alone. Every write passes through a human click on a card. This page walks the sequence; the tool reference has each tool's schema.

The sequence

  1. Find. The model calls find_business with a name, website, or domain. The server lists matches and shows a picker card. Each match is editable (the user holds a claim on it and its site is not live) or locked with a reason.
  2. Open. The user clicks a business on the card. The card calls open_session with a card token minted for that exact click; the server opens an edit session on the Edits API and returns the session_id to the model. The model cannot do this step.
  3. Read. The model calls get_snapshot with the session id: the profile and every record with its id, label, and version. read_business returns one record in full with its write field names.
  4. Propose. The model calls propose_changes with up to 50 change items, each carrying the expected values or version it read. The server stages a changeset; nothing is saved. The card shows each change, ticked, naming the business.
  5. Apply. The user unticks what they do not want and clicks Apply. The card calls apply_changeset with its token; SOR applies each item with compare-and-swap and writes it to Change History.
  6. Undo, if needed. The card offers Undo; undo_changeset reverts the applied items. A value changed again since the apply is kept.

Claims

A business can be edited only while the user holds a claim on it (24 hours, extendable) and its website is not live. A business nobody holds, and that has not launched, shows Claim on the picker; claim_business takes it. Live businesses are edited in the console, where Change History and Undo work the same way.

Sessions expire

A session has an expiry returned by open_session. After it, get_snapshot and propose_changes fail with a reason; find and open again.

Refusals

Anything SOR refuses (not claimed, launched, conflict, validation) comes back as the tool's text result with the code, and for a changeset, each refused item by position. The model is expected to fix and resend only those.