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 endpoint is a named, versioned tool-access configuration with an MCP URL. Add the URL to a coding agent or another MCP client to use the tools and permissions configured for the endpoint. Creating an endpoint does not start an agent, a chat conversation, or a running sandbox. Clients must support remote Streamable HTTP MCP servers and the required authentication and approval flow.

An endpoint belongs to a DigitalOcean team and is owned by the user who creates it. Ordinary endpoint names are unique within the team; automatically created default endpoints are an exception. The owner and actor ID remain the same across versions. A connection provides access to an external account. Connections must have the same owner, team, and actor as the endpoint; matching an actor ID alone does not grant access to another user’s connections. See Connection Ownership.

Default Endpoints

For an authenticated DigitalOcean user, the generic MCP URL https://actions.do-ai.run/mcp uses that user’s default endpoint in the current team. Action Gateway creates the endpoint on the first request. No endpoint creation step is required. Its initial configuration selects all catalog tools and asks for approval on every call. It does not authorize third-party provider accounts. Connect each provider using the default endpoint’s actor ID before using its tools.

The default actor ID is initially derived from the user’s email username, with the account UUID as a fallback. The actor stays the same if the email changes. The default endpoint is a normal public endpoint that you can inspect, rename, publish versions to, or delete. It does not count against the team’s endpoint limit. Its initial name is default, but this name is not unique and does not select the default. Renaming it or creating another endpoint named default does not change which endpoint the generic URL uses.

Endpoint API list, search, and get responses identify the current caller’s default in the team with is_default: true. Other endpoints have is_default: false, including another team member’s default when visible to a team owner. Listing endpoints does not create a default endpoint; the first generic MCP or data-plane request creates it.

Deleting the default endpoint causes the next generic request to create a new default endpoint with a new ID and the original all-tools, ask-for-approval configuration. Deleting all versions instead leaves the existing endpoint without a head; publish a new version to restore access. There is no supported way to designate an existing endpoint as the default. Harness Runtime uses its own run endpoint, not a user’s default.

Endpoint Versions

Each version contains a complete configuration, including tool selection, policy, instructions, preloads, output views, and VPC attachment. Versions are immutable. Publish a complete configuration to create a new version when these settings need to change. The head is the highest-numbered version that has not been deleted. Calls to the endpoint’s MCP URL use the head. The hostname can change when a new head changes the VPC region; copy the latest returned endpoint URL after changing the attachment.

To keep a client on one configuration, use that version’s MCP URL instead. Copy the URL returned for the version; it is separate from the version ID. The endpoint ID is a UUID, and version IDs have the form <endpoint-uuid>.v<N>. Do not construct an MCP URL from either ID.

You can promote an older live version to make a copy of its configuration the new head. For example, if versions 1 and 2 exist, promoting version 1 creates version 3; it does not alter version 1. Deleting the head makes the next highest live version the head. If you delete every version, MCP requests to the endpoint URL fail with JSON-RPC error -32001 and the message endpoint has no live version. Publish a new version to restore access. An endpoint can have up to 100 live versions. Delete an older version to make room before publishing or promoting another.

Insights consent belongs to the endpoint and applies to all versions, including pinned versions. Promoting an older version does not restore its earlier consent settings.

Head changes normally take effect within 10 seconds plus request skew. Calls already in flight continue with their bound version. During a registry transport failure, the gateway can use cached policy for up to 5 minutes. A deleted endpoint or head can therefore remain usable during that window. Deleted pinned versions can also remain usable for up to 5 minutes. Plan for these delays when revoking access.

Endpoint-scoped approval grants persist across published and promoted versions. Approval grants made through a pinned URL apply only to that version. In either case, the resolved version’s policy still governs each invocation.

When to Reuse an Endpoint

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

Account access is checked when tools execute. See Manage Action Gateway Endpoints and Restore Provider Access.

Action Gateway Endpoints and Harness Runtime Sessions

An Action Gateway endpoint configures tool access. A Harness Runtime session runs an agent in a sandbox and manages its workspace and execution. 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, an endpoint version 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

An endpoint version 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 version. 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 version 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 MCP URL unchanged. 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.

Endpoint Instructions

Endpoint 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 a version 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 MCP tools/list response. Configure it in the version 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 version can call. A permitted tool discovered through search can be invoked without being preloaded. 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 in a version 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 under the version 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. Another version or endpoint can use a different view or full output for the same tool.

To change a binding, publish a new version. See Add a Tool Output View and Manage Action Gateway Endpoints.

MCP URLs

Copy the endpoint or version MCP URL returned by Action Gateway and add it as a remote MCP server in your client. The endpoint URL follows the head; the version URL stays pinned to that version until it is deleted. These URLs differ from the temporary consent link used to authorize a provider account.

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

An endpoint does not preserve action_code sandbox state. Reusing the MCP URL preserves access to a tool configuration, not the files or variables from an earlier code execution.