Gamut

Integrations

Mapping Accounts to Agents

Connected accounts and MCP servers are registered once, then assigned to agents individually. An agent can only reach the integrations mapped to it.

How mapping works

Mappings live in two junction tables: agent_connected_accounts links an agent slug to a connected account ID, and agent_remote_mcps does the same for remote MCP servers. Each pair is unique, so an integration cannot be mapped to the same agent twice.

Assigning integrations to an agent

From the agent home page

  1. Open the agent and find the Connections section on its home page.
  2. Click the + button or the Settings button to open the connections view, which lists every available account and MCP server.
  3. Toggle the integrations this agent should have.

From the global connections page

  1. Open Settings > Connections and select a connected account or MCP server.
  2. The Agents pill shows which agents have it mapped. Click the pill to open the assignment dialog and add or remove mappings.

What agents receive at runtime

A running agent is told about its mapped integrations:

  • Connected accounts: each account's toolkit slug (such as gmail), display name, and the proxy URL for API requests.
  • Remote MCP servers: each server's proxy URL and tool list.

Every request passes through the secure proxy, which verifies the agent's synthetic token and the mapping before forwarding. A request to an unmapped account or server returns a 404 error ("Account not found or not mapped to this agent").

Many-to-many mappings

One account can serve several agents. A single Gmail connection mapped to both an "Inbox Manager" and a "Daily Digest" agent shares the same OAuth connection, while each agent can have different scope policies. The same applies to MCP servers, each mapping with its own tool policies.

One agent can also hold several accounts of the same provider, such as a personal and a work Gmail. The agent tells them apart by display name, which typically shows the email address.

Ownership in auth mode

In auth mode with multiple users, each connected account belongs to the user who completed its OAuth flow, tracked by the userId field on the account record. Users see and manage only their own accounts, and an account can only be mapped to agents its owner has access to. Admins see and manage all accounts regardless of ownership.

Removing a mapping

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

Removing a mapping only revokes the agent's access; the account or server itself is untouched and can be re-mapped at any time. Deleting the account or server, by contrast, removes all of its mappings at once.

Agent requests for new integrations

An agent that needs an unmapped integration can request one with a built-in tool:

  • Request Connected Account: The agent asks for a specific provider, such as Gmail. The prompt offers to connect a new account or select an existing one.
  • Request MCP Server: The agent asks for a specific server by URL or name. The prompt offers to register and connect it.

Requests appear inline in the session and require your explicit approval.

Related