OperateGovernanceMCP GatewaysMulti-profile support

Multi-profile support

Multi-profile support lets each of your users connect more than one account at the same provider, such as a work and a personal Google account, and lets their agents choose which one each tool call runs on. This page is for agent developers and platform operators who run Gateways for users with more than one at a provider. It explains what a is, what an MCP client gets when multi-profile support is on, how a call picks a profile, and what isn’t covered yet. An organization admin turns it on with the Multi-profile support switch on the Organization page of the Arcade Dashboard. It’s off by default.

Why it exists

Many people have more than one at the same provider: a work and a personal Google account, or several Slack workspaces. Without multi- support, each user connects one account per provider, and every for that provider acts as that account.

With multi-profile support on, a user can connect several , and the agent names the one each tool call runs on. Arcade doesn’t guess between them. When a user has more than one and a call names none, Arcade refuses the call and lists the user’s , so the can ask the which one they mean.

Profiles

A profile is one external that a user connected at a provider, such as a Google account or a Slack workspace. Users can connect more than one for these providers:

ProviderA profile isIts display name
GoogleA Google accountThe account’s email address
MicrosoftA Microsoft accountThe sign-in name, usually an email address
Microsoft Power BIA Microsoft accountThe sign-in name, usually an email address
SlackA Slack workspaceThe workspace name

Other providers still allow one connection per .

Each has an arcade_profile_id, the ID use to name it, and a display name. The display name comes from the provider, and nobody can rename it in Arcade.

When a user connects the same external twice, Arcade keeps a single for it. Connections that made before multi-profile support keep working as profiles.

What an MCP client gets

When multi- support is on, a gateway whose use one of these providers offers the following:

Tool or argumentWhat it does
arcade_profile_idAn optional argument on each tool whose provider supports multiple profiles. It names the profile the call runs on.
System_ManageProfilesLists the providers the gateway’s tools use, and the user’s profiles for each.
System_ManageAuthorizationTakes an optional profiles argument to check or authorize a named profile, or to connect another one.

arcade_profile_id shows in the gateway’s tools/list, and in the Arcade_SelectTools returns when Tool Recommendation is on. tools/call, Arcade_UseTool and Arcade_UseToolWithUI all accept it. Arcade removes it before the tool runs, so the tool never receives it. Tools for other providers are listed with only the arguments they declare.

Multi-profile support runs inside the gateway and speaks standard . The profile argument is an ordinary tool argument, and the profile a call used comes back in the tool result, so any MCP client that can connect to an Arcade can use it. The tool descriptions that Arcade serves tell the model how to name a , and each refusal tells it how to recover, so most need no extra prompting.

How a tool call picks a profile

When an agent calls a tool for a provider that supports multiple :

  • If the call names a in arcade_profile_id, it runs on that profile.
  • If the call names none and the user has one for the provider, it runs on that profile.
  • If the call names none and the has two or more, Arcade refuses it with connected_profile_required. The refusal lists each with its arcade_profile_id and display name. The asks the user which one to use, unless the user already said, and calls the again.
  • If the user hasn’t connected the provider yet, the call asks the user to authorize, as it does without multi- support.

On a direct call, arcade_profile_id goes with the tool’s other arguments:

{
  "name": "Gmail_ListEmails",
  "arguments": {
    "n_emails": 5,
    "arcade_profile_id": "2qR8sNvYk3TmB7cXw1LpJ5fHdZe"
  }
}

Through Arcade_UseTool, it goes inside inputs, next to the ’s own arguments:

{
  "tool_name": "Gmail.ListEmails",
  "inputs": {
    "n_emails": 5,
    "arcade_profile_id": "2qR8sNvYk3TmB7cXw1LpJ5fHdZe"
  }
}

arcade_profile_id takes a ID, never a display name or email address. An gets profile IDs from System_ManageProfiles, from a status check with System_ManageAuthorization, from a connected_profile_required refusal, or from an earlier result.

See which profile a call used

Each tool result tells the agent which the call used. A note after the ’s output names the profile by its display name and arcade_profile_id, whether the tool succeeded or failed. If the tool didn’t answer, for example because it timed out, the note says which profile was selected for the call, without saying that the call ran.

The result’s _meta["dev.arcade/profile"] carries the same , with its provider_id, arcade_profile_id and display_name. An App can read it to show which profile a result came from. The App’s own tool calls follow the same rules as the ’s, so to keep them on the same profile, the App passes this arcade_profile_id on each call to a for the same provider.

When a profile needs authorization

A tool call can need the user to authorize one of their profiles, for example when the tool needs a permission that profile hasn’t granted yet. The result then names the profile and tells the agent which the must sign in with. A client that supports URL elicitation shows the user that account when it asks them to sign in.

If the user signs in with a different , the authorization fails, and the keeps the access it had.

Manage profiles from the agent

List profiles

System_ManageProfiles appears on a gateway while multi- support is on and at least one of the gateway’s uses a provider that supports multiple profiles. It has three actions:

ActionWhat it does
list_providersLists the providers the gateway’s tools use. Each says whether it supports multiple profiles, and each one that does lists the user’s profiles.
list_profilesLists the user’s profiles for each provider the gateway’s tools use that supports multiple profiles. Pass provider_id to list one provider’s profiles.
check_multi_profile_supportSays whether the provider in provider_id supports multiple profiles.
{
  "action": "list_profiles",
  "provider_id": "google"
}

Each in the result has its arcade_profile_id, its display name, whether it’s connected or needs authorization, and the permissions it grants. The lists only the ’s own profiles. Provider IDs come from list_providers. Asking to list profiles for a provider that allows one connection per user is refused.

Check and authorize each profile

System_ManageAuthorization checks and requests the authorization a job needs. While multi- support is on, it takes an optional profiles argument, with at most one entry per provider. Each entry’s provider_id must be the provider of one of the in tools.

A status check reports each of the user’s for a provider on its own, with its own status. With profiles, it reports only the providers listed there, and an entry with an arcade_profile_id checks only that profile.

To authorize a named , pass its provider_id and arcade_profile_id:

{
  "action": "authorize",
  "tools": ["Gmail_SendEmail"],
  "profiles": [
    {
      "provider_id": "google",
      "arcade_profile_id": "2qR8sNvYk3TmB7cXw1LpJ5fHdZe"
    }
  ]
}

If that already grants the permissions the need, the result reports it as authorized, and there’s nothing more to do. Otherwise, a client that supports URL elicitation asks the user to authorize the profile. Any other client gets a link in the response, which the shows the . Without an entry for a provider, authorize uses the user’s only profile for it. If they have several, the call is refused and asks the agent to name one. A call that names a profile the user doesn’t have, or names one by anything but its ID, is refused and points the agent to a status check.

Connect another profile

To connect another , pass an entry with only a provider_id:

{
  "action": "authorize",
  "tools": ["Gmail_SendEmail"],
  "profiles": [{ "provider_id": "google" }]
}

The result has a link where the user signs in with the they want to add. The provider’s sign-in page may suggest an account they already connected, such as the Google account their browser is signed in to. If so, they should choose the account they want to add instead. The link always comes back in the tool’s response, with instructions for the , even to a client that supports URL elicitation. The agent shows the link to the .

Once the user finishes, a status check shows the new profile, which the agent finds by its display name. If the user signed in with an they had already connected, no new appears, and Arcade updates the existing one instead.

Connecting another is refused for a provider that allows one connection per .

Errors

A tool call that can’t run on a is refused with one of these errors. Each refusal tells the how to recover.

ErrorWhat it meansHow the agent recovers
connected_profile_requiredThe user has more than one profile for the tool’s provider, and the call didn’t name one.The refusal lists each profile with its arcade_profile_id and display name. The agent asks the user which one to use, unless the user already said, and calls the tool again with that profile.
unknown_profileThe user has no profile with that arcade_profile_id for the provider. This includes a display name or an email address passed instead of an ID.The agent lists the user’s profiles with System_ManageProfiles and calls the tool again with one of their IDs. If the profile the user means isn’t connected yet, the agent connects it with System_ManageAuthorization.
unavailable_profileMulti-profile support is off for the organization, and the call named a profile other than the one it runs on.The agent calls the tool again without arcade_profile_id.

What’s not covered

  • The and SDKs. Support is coming soon. Until then, POST /v1/tools/execute, POST /v1/tools/authorize and POST /v1/auth/authorize take no arcade_profile_id, and use the user’s oldest for the provider. GET /v1/apps and the -definition endpoints don’t show profiles.
  • Remote servers. Multi- support works only with Arcade-hosted servers, and is coming soon to remote MCP servers.

Last updated on

On this page