--- title: Sessions (public) description: An Action Gateway session gives you an MCP endpoint URL with the tools and permissions you choose for your client. product: Managed Agents url: https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/sessions/ last_updated: "2026-10-14" --- > **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). # Sessions (public) Action Gateway gives applications and AI agents governed access to tens of thousands of tools through a managed MCP endpoint or SDK. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases of Action Gateway with Harness Runtime. 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md#connect-an-external-mcp-client). The session’s [actor ID](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/actors/index.html.md) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/connections/index.html.md#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](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-sessions/index.html.md). ## 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md) to add known tool definitions to the initial tool list. Configure [output views](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/sessions/index.html.md#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](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/code-execution-tool/index.html.md) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/use-private-tools/index.html.md) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-policies/index.html.md) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/add-tool-output-view/index.html.md) for view creation and [Manage Action Gateway Sessions](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-sessions/index.html.md#override-tool-output-for-the-session) 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](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md) 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.