Gamut

Mapping Accounts to Agents

How to assign connected accounts and MCP servers to specific agents, controlling which integrations each agent can access.

Superagent uses an explicit mapping model: a connected account or MCP server is only accessible to an agent if you have specifically assigned it. This gives you fine-grained control over which services each agent can use.

How Mapping Works

Both connected accounts and remote MCP servers are registered at the application level. They are not inherently tied to any agent. To make an integration available to an agent, you create a mapping between the two.

Under the hood, these mappings are stored in junction tables:

  • agent_connected_accounts — Links an agent slug to a connected account ID.
  • agent_remote_mcps — Links an agent slug to a remote MCP server ID.

Each mapping is unique — you cannot map the same account to the same agent twice. When a connected account or MCP server is deleted, all of its agent mappings are automatically removed.

Assigning Integrations to an Agent

From the Agent Home Page

  1. Open the agent you want to configure.
  2. In the Connections section of the agent home page, click the + button or the Settings button.
  3. You will see the connections management view, which shows all available accounts and MCP servers.
  4. Toggle the integrations you want to assign to this agent.

From the Global Connections Page

  1. Navigate to Settings > Connections.
  2. Click on a connected account or MCP server.
  3. Use the Agents pill to see which agents currently have this integration mapped.
  4. Click the agents pill to open the agent assignment dialog, where you can add or remove agent mappings.

What Happens at Runtime

When an agent runs, the system provides it with information about its mapped integrations:

  • For connected accounts, the agent receives a list of available accounts with their toolkit slug (e.g., gmail), display name, and the proxy URL to use for API requests. The agent authenticates to the proxy with a synthetic token that is unique to that agent. The proxy verifies both the token and the agent-account mapping before forwarding any request.

  • For remote MCP servers, the agent receives the MCP server's proxy URL and the list of available tools. The MCP proxy similarly validates the agent-MCP mapping before forwarding tool calls.

If an agent tries to use an account or MCP server that is not mapped to it, the proxy returns a 404 error ("Account not found or not mapped to this agent").

One Account, Many Agents

A single connected account can be mapped to multiple agents. For example, you might have one Gmail account connected and map it to both your "Inbox Manager" agent and your "Daily Digest" agent. Both agents share the same OAuth connection but can have different scope policies.

Similarly, a single MCP server can be mapped to multiple agents, each with their own tool policies.

One Agent, Many Accounts

An agent can have multiple accounts of the same provider type. For example, you might map two different Gmail accounts to an agent — one for personal email and one for work email. The agent distinguishes them by the account's display name (which typically shows the email address).

Multi-User Account Ownership (Auth Mode)

When Superagent runs in auth mode with multiple users:

  • Each connected account has an owner (the user who completed the OAuth flow). The userId field on the account record tracks this.
  • Users can only see and manage their own accounts. The API scopes all account queries to the current user's ID.
  • Agent mappings reference accounts by ID, so an account can only be mapped to agents that the account owner has access to.
  • Admins can see and manage all accounts regardless of ownership.

This ensures that in a shared Superagent instance, users' OAuth credentials and account access are isolated from each other.

Removing a Mapping

To remove an integration from an agent:

  1. Open the agent's Connections section.
  2. Click the remove button on the integration you want to unmap.

Removing a mapping does not delete the connected account or MCP server itself — it only removes the agent's access to it. You can re-add the mapping at any time.

Agent Requests for New Integrations

If an agent needs an integration that is not currently mapped, it can use a built-in tool to request one:

  • Request Connected Account — The agent asks for a specific provider (e.g., Gmail). You see a prompt in the chat session where you can connect the account or select an existing one.
  • Request MCP Server — The agent asks for a specific MCP server by URL or name. You see a prompt to register and connect the server.

These requests appear inline in the conversation and require your explicit approval.

Related