Skip to main content
Preview. /mcp/v3 is behind a feature flag and no accounts are enrolled. Nothing on /mcp/v2 changes, and no migration is required or proposed. This page describes what the surface is so you can judge it early, not so you can build against it yet.

​
One endpoint, not one per persona

v2 is persona-scoped: you pick /mcp/v2/buyer or /mcp/v2/storefront, and the URL decides what you can do. v3 inverts that. There is one endpoint, and the tools you see are resolved from the account you authenticated as. A seller account yields seller tools; a buyer account yields buyer tools. You do not choose a persona — you authenticate, and the surface follows. This matters because the persona split was never real to the person. One human might administer an organisation, own a storefront, and buy through two advertiser seats. In v2 that is three MCP servers. In v3 it is one connection and a switch_account.

​
Nouns crossed with a fixed verb set

v2 exposes a generic api_call tool over a large named-operation enum. It works, but it asks the model to pick an operation and then guess the body shape. v3 is the platform’s nouns crossed with a fixed verb set, so adding a capability means adding a field to a noun — never appending to an enum. Reads generalise safely and cannot corrupt anything. Writes carry a per-noun body, so each gets its own tool with its own schema.

​
Orientation, and knowing you are in the wrong place

MCP negotiates the tool list once, at initialize. If switching accounts changes which tools exist, a client that missed notifications/tools/list_changed would be holding a stale list. v3 does not depend on that notification:
1

get_status always lists the accounts you can reach

Orientation never requires switching in order to discover what switching would give you. It returns the current account, what is blocking it, what to do next, and every other account reachable from here.
2

Every tool fails legibly in the wrong account

Calling a seller tool from a buyer account returns a typed error naming the exact switch_account call that reaches an account where it exists.
3

tools/list_changed is emitted anyway

Conforming clients get a clean surface. Clients that ignore it lose nothing, because the first two carry the weight.

​
Diagnostics are an include, not a tool

Health, sync history and capability rechecks are facts about an object, so they are an include on the object rather than a second tool name to learn:
A source can hold valid credentials and still be failing every call, so connection (do we hold usable credentials?) and health (is it working?) are reported side by side. They are different questions and they disagree often enough to matter.

​
Asking for something the account cannot give you

save_ask covers the two things no account can resolve on its own:

support

Something is broken or blocking. Reaches the Scope3 team the same way a problem reported in Murph chat does, and returns a reference id to quote when you follow up.

product

A capability that does not exist. If someone already asked, yours joins that entry rather than creating a duplicate. Only the title is recorded, so make the title carry the request.
Tracking an ask is not a commitment to build it. save_ask works from any account and needs only read permission — whoever runs into a wall is usually not whoever has permission to fix it.

​
Limits

  • Structured responses over 200KB are truncated. A backstop against pathological payloads, not a size to design against.
  • Preview scope. The storefront account is built out first; buyer and organisation accounts follow. get_status and switch_account work in every account, including one that is not enrolled — so you are never stranded somewhere you cannot leave.

​
What is not changing

/mcp/v2/buyer and /mcp/v2/storefront stay supported. v3 is a facade over the same services, so it owes parity with what v2 can do — it is a different way in, not a different platform underneath. No deprecation is proposed.