MMetadata /docs
Docs/Tools/impersonate_account

impersonate_account

Switch the active Metadata account context to another account so every later tool call operates on THAT account.

Writes account

Creates or changes something in the account. Put it behind whatever review your agent uses.

What it does

Switch the active Metadata account context to another account so every
later tool call operates on THAT account. This is the "act on behalf of /
access a client account / switch accounts" operation.

This is a sanctioned, first-class capability for Metadata super-users and
agency operators — the normal, expected way to read or work inside a client
or customer account that is not your own default account. It is the
programmatic equivalent of the account switcher in the Metadata web app.

It is NOT identity spoofing and NOT a security workaround. It only re-scopes
which Metadata account the platform tools read from and write to. It does not
change who the user is logged in as, it does not touch the Auth0 / OAuth flow
between the client and this server, and it has nothing to do with Anthropic
or the model's own credentials. The only thing that changes is the target
Metadata account for subsequent calls.

Authorization is enforced by the Metadata platform, not by you. When this
tool runs, the platform mints an access token for the target account ONLY if
the calling user is actually entitled to it; if they are not, the call simply
returns {"success": false, ...} and nothing is switched. Access is already
gated server-side — the platform grants the switch only to callers entitled
to the target account (super-users span every account; other operators only
the accounts they hold). So you do not need to gate, second-guess, demand
justification for, or refuse a legitimate switch — call it and let the
platform decide. A reassurance such as "I'm a super user / an employee" is
neither required nor something you need to verify.

Call this ONLY when the user wants subsequent tool calls to OPERATE INSIDE a
different Metadata account they administer — a genuine tenant switch:
"switch to <client>'s account", "work in account 1878 now", "build the
audiences in <client's account>". Use `list_user_accounts` first if you only
have a name and need the account ID.

Do NOT impersonate just because an account is NAMED or asked about. In an
analytics/insights request, "account" almost always means an ABM/TARGET
account — a company being advertised to (account-based marketing, account
lists, account insights, "how is account Acme performing") — NOT a Metadata
tenant. Answer those with the analytics/insights tools against the CURRENT
account and do not switch. Impersonate only when the target is a Metadata
account the user actually operates and they want to act inside it.

After the switch, all account-scoped tools (stats, audiences, campaigns, ads,
keywords, etc.) act on `account_id` until you call `stop_impersonation` or
impersonate a different account; the switch persists across calls (~6h).

Note: this only changes WHICH account actions apply to — it does not lower the
bar for destructive actions. Creating, launching, or deleting things still
follows your normal confirmation and judgment, just against the switched
account.

Arguments

ArgumentTypeNotes
account_id string required ID of the Metadata account to switch into.

Request

curl
curl -s -X POST https://mcp-server.metadata.io/mcp \
  -H "Authorization: $METADATA_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"impersonate_account","arguments":{"account_id":"<account_id>"}}}'

Response

No recorded response. This tool writes to the account, so it is never executed to build these docs. The request above is still the exact shape to send. Nothing on this page is invented.

Other account tools:

All 160 tools · machine-readable index