Skip to content

Multi-account connections

A person who is owner or admin of several accounts can tick one, several or all of them on the OAuth consent screen. One connection then covers all of them, with one agent per account. API keys always belong to one account and are not affected.

Nothing changes: no accountId, no list_accounts.

  1. The server instructions say so: call list_accounts first, then pass accountId on every call, and never copy records between accounts unless the person asks.

  2. list_accounts returns the accounts this connection may act in:

    { "data": [
    { "id": "…", "name": "NanaNido", "baseCurrency": "EUR", "timezone": "Europe/Madrid",
    "agent": { "id": "…", "name": "Claude", "title": "via Ana" },
    "scopes": ["records:read", "records:write", "feedback:write"] },
    { "id": "…", "name": "InmoPublic", "…": "…" }
    ] }
  3. Every other tool takes accountId (an id from that list) and runs as that account’s agent, with that account’s scopes:

    { "name": "query_records", "arguments": { "accountId": "…", "type": "deal",
    "filters": [{ "field": "stage.outcome", "op": "eq", "value": "open" }] } }
  4. whoami without accountId returns { "type": "connection", "accounts": [ … ] }; with one, the agent of that account.

Mistake Tool error
No accountId ACCOUNT_REQUIRED, with details.accounts: [{ id, name }]
An account outside the connection ACCOUNT_NOT_FOUND, with details.accounts

The tool list shows every tool any of the accounts allows: if only one account granted pipelines:manage, the pipeline tools are listed, and calling them with another accountId returns FORBIDDEN. Scopes are also narrowed to what the person’s current role allows in each account.

  • Connecting again shows the consent screen; the new choice replaces the set. Accounts left out are disconnected (their agent is archived).
  • Accounts the person joins later are never added on their own.
  • Archiving the connection’s agent in one account’s Settings → Agents removes only that account.

Rate limits are counted per connection, not per account.