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 gives you an MCP endpoint (URL) with the tools and permissions you choose. Add the URL to an MCP client, such as a coding agent, OpenClaw, Hermes, or ChatGPT, to give it access to those tools. Creating the session configures tool access; it does not start an agent or create a chat conversation.

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.

The session’s actor ID is a user-defined identifier that selects the provider connections its tool calls use. If you have separate work and personal connections to the same provider, choose the actor associated with the account you want this session to use.

Sessions created through the Control Panel or public API belong to the authenticated DigitalOcean user within the selected team. Create provider connections as that user and assign the same actor ID. Matching an actor ID alone does not authorize access to another user’s connections. See Connection Ownership.

Session configuration is set at creation. To change the actor, tool selection, permission policy, instructions, preloads, output views, or VPC attachment, create a replacement session and connect clients to its returned URL. See Manage Action Gateway Sessions.

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 Connect Private Tools 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. Copy this value verbatim and add it as a remote MCP server in your client’s configuration. Do not build the URL from the session ID or replace its hostname: the returned URL identifies the environment that owns the session. Calls through that URL use the session’s tool selection, permissions, and actor connections.

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.