---
title: How to Manage Action Gateway Sessions (public)
description: Create an Action Gateway session to get an MCP endpoint URL with the tools and permissions your client needs.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-sessions/
last_updated: "2026-10-22"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Manage Action Gateway Sessions (public)

Action Gateway connects applications and AI agents to tools through a managed MCP endpoint or SDK, with the accounts and permissions you choose. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/action-gateway/details/what-you-can-build/index.html.md) for standalone agent examples.

Create an Action Gateway session to save the tools and permissions you want and get an MCP endpoint URL for that configuration. Add the URL to your coding agent or other MCP client, then authenticate with DigitalOcean. Reuse it for later tasks that need the same access. Creating a session does not start an agent or a conversation.

By default, the MCP client receives three meta tools for discovery, invocation, and code execution rather than every catalog tool’s definition. During session creation, you can also preload known tools, choose output views, add instructions, or attach a VPC.

## Prerequisites

- Access to Action Gateway for your DigitalOcean team.
- For tools that access external accounts, [connections to those accounts](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-connections/index.html.md) or a plan to authorize them before use. You can create these before or after the session.

Some tools, including Exa web search and web fetch, require a [positive prepaid balance](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-ag-prepayment/index.html.md). Prepayment is not required for every tool.

## Configure the Session

In the [DigitalOcean Control Panel](https://cloud.digitalocean.com/managed-agents/action-gateway/sessions), open **Managed Agents**, select **Action Gateway**, then open **Sessions**. Click **Create session**.

Enter a **Session Name** and select or enter the **Actor ID**. For your own coding agent, keep the [Control Panel default](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/actors/index.html.md#default-actor-id) and use it when connecting accounts. For an application serving multiple users, use the label assigned to the person whose accounts this session should access, such as `user-123`.

Connections with that ID, owned by the same DigitalOcean user in the same team, supply the accounts this session uses. Reuse the ID across sessions that need the same accounts. See [Choosing an Actor ID](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/actors/index.html.md#choosing-an-actor-id) for separate work and personal accounts.

Under **VPC Attachment**, select a VPC for workloads that use private tools or need `action_code` to access private resources. VPC networking must be enabled for your team. The VPC must belong to your team in `ric1`. Leave **No VPC attachment** selected for workloads that only need public tools.

Create the provider connection with the same owner, team, and actor ID as the session. Configure its VPC and allowed destinations separately. The session attachment does not create a connection or grant it access to every address in the VPC.

For a first private provider, select the same VPC on the session and connection. The enforced session restriction is a matching region. A private MCP connection must also match the server’s exact registered VPC ID. Public connections retain public networking, even in an attached session. See [Access Tools and MCP Servers on a Private Network](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/use-private-tools/index.html.md).

Under **Session instructions (optional)**, click **Add instructions** to supply up to 1,000 characters of guidance. The MCP client receives these instructions during initialization. Do not include secrets, and do not use instructions as a replacement for permission rules.

The **Configuration** section groups the session name, actor, VPC attachment, and instructions:

![Session configuration with example session and actor names, no VPC attachment, and optional instructions.](https://docs.digitalocean.com/screenshots/action-gateway/session-configuration.370694e92b53e930101049f44044e96d9237ab26c175a3e0af7ced31fc5b7871.png)

For a private workload, select a VPC under **VPC Attachment**. This example shows the session name, actor ID, and attached VPC with its name and ID replaced:

![Session configuration with an example session name and actor ID, and a VPC selected in ric1. The VPC name and ID are example values.](https://docs.digitalocean.com/screenshots/action-gateway/session-vpc-attachment.c7ed6d3fd73d6f7c9fe51050d5c9b06da5b2f58a01bcec53ee547e5ecb6eded4.png)

For API session creation, set `network.vpc_uuid` to the VPC ID. Include it alongside the session’s actor, tools, and policy:

```json
{
  "network": {
    "vpc_uuid": "<vpc-uuid>"
  }
}
```

Action Gateway validates the VPC’s ownership and derives its region. Omit `network` to create a session without an attachment. Use the returned MCP URL unchanged so private calls reach the session’s regional gateway.

## Set Tool Access and Permissions

Under **Permission policy**, choose a **Default Action**:

- **Ask:** Require approval before a tool runs. Use a client that can complete the [approval flow](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/configure-server-side-approval/index.html.md).
- **Allow:** Run calls without gateway approval unless a more-specific rule says otherwise.
- **Deny:** Block calls unless a more-specific rule permits them.

Select **All tools** for catalog-wide access or **Selected tools** to restrict the session to chosen tools and Toolbelts. An allow rule cannot widen **Selected tools** access.

For an issue-triage agent, select tools for reading GitHub and Linear issues, allow those reads, and require approval for commenting or updating issues. Selecting these tools does not connect either account. [Authorize the accounts](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-connections/index.html.md) using the session’s actor ID before relying on them.

Search the tool list and select the tools or versioned Toolbelts the session needs. Set each entry’s **Action** where it should differ from the default. A Toolbelt rule applies to its member tools. A more-specific tool rule can override it. See [Tool Policies](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-policies/index.html.md).

## Preload Frequently Used Tools

In the session’s tool list, enable **Preload** for tools or Toolbelts the workload regularly needs. Their tool definitions appear alongside the three meta tools in the MCP client’s tool list. The agent can use them without first searching for their names and inputs.

Keep the preload set small. Preloading avoids discovery for known tools, but it adds definitions to model context even when a task does not use them. Leave **Preload** off for tools the agent should discover as needed with `action_search`.

Preloading does not grant permission or restrict discovery to the preloaded set. Other permitted tools remain searchable. For the API equivalent, set `config.preloadTools` when creating the session. See [Preloading Tools](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md).

## Override Tool Output for the Session

Select a tool and use its **Output view** control to choose a view instead of **Full output**. The view overrides the fields returned by that tool for this session. If no suitable view exists, [create an output view](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/add-tool-output-view/index.html.md) that keeps the fields the workload needs, then select it during session creation.

For example, choose a view with record IDs and names when the agent does not need the rest of each record. Removing unrelated fields reduces the tool-result data the model reads and can lower inference-token costs. The tool still runs its normal operation and incurs any applicable tool usage charges.

This example preloads Exa Web Search, requires approval for its calls, and binds an existing `only_urls` output view:

![Session tool controls with Exa Web Search selected, Preload enabled, the ask action, and the only_urls output view.](https://docs.digitalocean.com/screenshots/action-gateway/session-tool-controls.0e03e71024b6552607a2a1822e219c2c43fbcf43f2012780ff276b9c50ab5378.png)

This override applies to every call to the tool in the session, including preloaded tools, `action_invoke`, and calls inside `action_code`. It does not change the tool’s output in other sessions. In the API, set `config.outputViews` to map each tool slug to its view name. See [Output Views](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/sessions/index.html.md#output-views).

## Create the Session

Review the policy before clicking **Create Session**. Broad allow rules can permit writes, deletions, and other changes to connected accounts without a gateway prompt.

## Connect and Inspect the Session

Copy the session’s MCP URL and add it as a remote MCP server in your client. [Follow your client’s setup and authentication steps](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md#connect-an-external-mcp-client) using the DigitalOcean account that created the session, in the same team. Calls through this URL use the tools and permissions you configured.

From **Sessions**, open the session to inspect its actor, tools, policy, instructions, VPC attachment, and output-view bindings. Use a read-only call to verify the intended access before running a workload that changes provider resources.

## Replace a Session’s Configuration

Session configuration is set at creation. Create another session to change its actor, tool selection, policy, instructions, preloads, output views, or VPC attachment. Update the client’s MCP configuration to use the replacement session’s returned URL.

Do not assume that replacing a session undoes provider actions or revokes the actor’s connections. Manage provider authorization separately through [Connections](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-connections/index.html.md).

Do not replace the session solely because a provider needs another sign-in. [Restore the connection’s access](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-connections/index.html.md#restore-provider-access) for the same actor, then continue using the existing MCP URL.