Skip to main content

​
One connection, account-resolved tools

v2 chooses a persona through the URL. v3 connects to one URL and resolves its catalog from the active account. A person who can administer an organisation, sell from a Seller Account, and buy through multiple Buyer accounts can move between them without registering multiple MCP servers. The active account is durable session context. Always begin with get_status, and call it again after switch_account.

​
Orientation is always available

get_status returns:
  • the active account and account kind;
  • readiness and transaction state when available;
  • blockers and typed next actions;
  • ready buyer destinations where applicable; and
  • a bounded list of reachable accounts that says when it is truncated.
get_status and switch_account remain available outside the preview cohort. This is a navigation exception, not access to unenrolled account data.

​
Nouns and verbs

v3 uses a small verb vocabulary over account-owned nouns: Reads can share a safe envelope. Writes cannot: each save_<noun> has its own schema so a model does not choose an operation name and then guess the body.

​
Tool discovery is part of the contract

The catalog may differ by:
  • account kind;
  • enrollment;
  • permissions;
  • feature rollout; and
  • MCP App support in the host.
Treat tools/list as the source of truth for names and JSON Schemas in the active account. The tool catalog explains the stable families and intended workflows; it does not replace runtime discovery. When an account switch changes the catalog, v3 emits notifications/tools/list_changed. If a client misses the notification, a wrong-account call returns a typed error that names the required account kind and an eligible switch_account call.

​
Tasks, Pages, and model visibility

Some work should not be represented as model-authored fields. OAuth grants, credentials, payout destinations, legal acceptance, and certain review actions belong in a human-facing Page.
  • A model-facing tool may return a Page as the next action.
  • open_page opens a named Page with bounded focus parameters.
  • Resource-bound MCP App tools may be present on the wire but hidden from model context by their visibility metadata.
Do not bypass a Page by placing credentials, bank details, or authorization decisions in another tool’s free text.

​
Declarative writes

A save_<noun> call states the desired noun state. Responses distinguish:
  • created or updated — a write occurred;
  • unchanged — the current state already matched;
  • pending_approval — a governed change was proposed, not committed; and
  • an error or partial-write result — the response explains what did and did not persist.
Send patches, not reconstructed whole objects, unless a schema explicitly asks for replacement. Preserve returned identifiers exactly. Qualified product and proposal IDs encode seller routing and must not be shortened or rebuilt.

​
Concurrency and idempotency

These mechanisms answer different questions:
  • expectedRevision prevents overwriting a newer object state. Re-read after a REVISION_CONFLICT and decide whether the intended change still applies.
  • idempotencyKey deduplicates one logical attempt where the tool promises it. Reusing a key for different intent is an error; inventing a new key for every retry can duplicate work.
  • correlationId, where offered, is a tracing handle and is not necessarily an idempotency key.
Use the exact semantics in each tool’s runtime schema and workflow guide.

​
Includes keep diagnostics attached to the object

Health, sync history, and capability evidence are facts about a resource, so they are generally requested through get.include:
Successful facts remain available when another requested include cannot be resolved. A response marks unsupported or partial detail instead of presenting it as an empty result.

​
Pagination and completeness

Pass the returned opaque nextCursor back to the same query while hasMore is true. Do not edit, reuse across kinds, or interpret a cursor. A partial response must say what was not reached; an empty items array alone is not evidence that the underlying system contained no results.