For AI agents: The documentation index is at 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).

An Action Gateway session is a saved tool-access configuration with its own MCP endpoint URL. Choose the tools and permissions, then add the URL to a coding agent or another MCP client, such as OpenClaw, Hermes, or ChatGPT. Creating a session does not start an agent, a chat conversation, or a running sandbox.

The session determines which tools the client can use and whether calls are allowed, require approval, or are denied. You can reuse its URL across tasks that need the same access. Clients must support remote Streamable HTTP MCP servers and the required authentication and approval flow.

For tools that access an external account, a connection saves access to that account. The session’s actor ID identifies whose connections to use. One session can use several connections, such as the GitHub and Linear accounts assigned to user-123.

Create the session and connections under the same DigitalOcean user and team, with the same actor ID. Matching an actor ID alone does not grant access to another user’s connections. See Connection Ownership.

When to Reuse or Replace a Session

For an issue-triage agent, select issue-reading and commenting tools, allow reads, and require approval for comments. Reuse that MCP URL for later triage tasks that need the same accounts and permissions.

Session configuration is set at creation. Account access is checked when tools execute. See Manage Action Gateway Sessions for setup and Restore Provider Access for reconnection.

Action Gateway and Harness Runtime Sessions

An Action Gateway session configures tool access. A Harness Runtime session runs an agent in a sandbox and manages its workspace and execution. They are different resources, even though both use the word session.

When you configure do.actions in Harness Runtime, it creates the associated Action Gateway endpoint and connects the agent automatically. You do not need to create and copy a standalone MCP URL for that integration. See Connect Action Gateway to Harness Runtime.

Model Context

By default, the session exposes three meta tools through MCP: action_search, action_invoke, and action_code, subject to its permission policy. The client does not need to load every catalog tool’s definition. The agent discovers relevant tools through search as it works.

Configure preloading to add known tool definitions to the initial tool list. Configure output views to reduce the fields returned by tool calls. These settings control different sources of model tokens: tool definitions and tool results.

VPC Attachment

A session can attach to a VPC owned by the same DigitalOcean team. VPC networking must be enabled for your team and is available in ric1. Action Gateway validates the VPC and records its region when it creates the session. The attachment allows the action_code sandbox to interact with resources inside that VPC.

Private provider calls use the VPC and destination grants on the actor’s connection. An attached session can use private connections in its VPC’s region. Their VPC IDs do not have to be identical. A private MCP connection must separately match its server’s registered VPC ID and region.

The attachment does not route every catalog provider call through the VPC. Public connections retain public networking, and calls inside action_code still use each provider connection’s settings. Neither attachment nor a connection’s destination list replaces authentication or the private service’s network controls.

Use the returned session MCP URL unchanged. It routes the client to the session’s regional gateway. Action Gateway does not support cross-region private calls. See Access Tools and MCP Servers on a Private Network for the network model and setup.

Session Instructions

Session instructions provide guidance to the MCP client, such as checking an issue tracker before creating duplicate work. The gateway appends them to its standard server instructions in the MCP initialization response.

The config.customInstructions field accepts up to 1,000 characters. Instructions are visible to the client and model, so do not include credentials or sensitive account data. Instructions guide behavior. Tool policies enforce permissions.

Tool Policy

Tool selection and permission policy are separate controls. Selection bounds the catalog the session can reach. The policy determines whether each eligible call runs, requires approval, or is denied.

For API requests, omitting tools selects the full catalog, tools: [] selects no catalog tools, and a non-empty array selects only its referenced tools and Toolbelts. Direct tools can be version-pinned. Toolbelt references require a version, such as toolbelt:read-only@1.

The meta tools have their own policy decisions. Restricting the catalog to a small selection does not by itself disable action_search, action_invoke, or action_code.

Preloading Tools

Preloading exposes selected tool definitions alongside the meta tools in the session’s MCP tools/list response. Configure it when creating the session, either with Preload in the Control Panel or the config.preloadTools array, which can contain tools or versioned Toolbelts.

Use preloading for a small set of operations the workload already knows it needs. The agent can call these tools without first using action_search, avoiding discovery for those operations. Each preloaded definition adds to the client’s tool list and can increase model input tokens, even when the tool is not used. Leave other tools available through search rather than preloading the entire selection.

Preloading controls what the client loads into context, not what the session can call. A permitted tool discovered through search can be invoked without being preloaded. Conversely, preloading does not grant access to a tool outside the selection or override a deny rule. Unknown, unavailable, or out-of-selection preloads are skipped.

See Preloading Tools for when to preload, search, or combine the two approaches.

Output Views

An output view limits the fields returned for a tool. Choose a view when creating the session to override the full result for that tool. For example, a workflow that needs record IDs and names can omit unrelated metadata instead of sending it to the model on every call. Smaller results can reduce model input tokens and associated inference costs. They do not reduce the tool’s usage charges.

In the API, bind views through config.outputViews, which maps tool slugs to view names. Every invocation of that tool in the session uses the view, including calls inside action_code and calls to preloaded tools. Clients cannot bypass the binding by requesting full output on an individual call. The binding belongs to the session, so another session can use a different view or full output for the same tool.

Keep the fields the workload needs to complete its task. To change a session’s binding, create a replacement session. See Add a Tool Output View for view creation and Manage Action Gateway Sessions for session configuration.

MCP URLs

Session creation returns an mcpUrl. Add the returned URL as a remote MCP server in your client’s configuration. Calls through it use the session’s tool selection, permissions, and actor connections. This endpoint is different from the temporary consent link used to authorize a provider account.

Authenticate with the DigitalOcean account that owns the session, in the same team. Knowing the URL or belonging to the team does not authorize another user to execute calls in that session. See Connect Action Gateway Tools for client setup and authentication options.

An Action Gateway session does not preserve action_code sandbox state. Reusing the MCP URL preserves the tool-access configuration, not the files or variables from an earlier code execution.