> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# v3 Agent Surface (preview)

> One MCP endpoint whose tools are resolved from the account you connect as — noun-shaped, typed, and no generic dispatcher

<Note>
  **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.
</Note>

## 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.

| Verb          | Shape                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search`      | Generic read over a `kind`. Uniform request, typed response.                                                        |
| `get`         | One object by id, with related detail via `include`.                                                                |
| `save_<noun>` | **Typed per noun.** Create-or-update; the write body is where shape errors actually happen, so it is never generic. |

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```json theme={null}
{ "kind": "inventory_source", "id": "my-source", "include": ["diagnostics"] }
```

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:

<CardGroup cols={2}>
  <Card title="support" icon="life-ring">
    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.
  </Card>

  <Card title="product" icon="lightbulb">
    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.
  </Card>
</CardGroup>

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.