---
title: How to Manage Action Gateway Endpoints (public)
description: Create and manage Action Gateway endpoints and their versioned tool-access configurations.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/manage-endpoints/
last_updated: "2026-11-05"
---

> **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 Endpoints (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 endpoint to give a coding agent or other MCP client access to the tools and permissions you choose. The endpoint URL follows the latest live version of its configuration. You can also use a version URL to pin a client to one configuration. Creating an endpoint does not start an agent or a conversation.

**Note**:

  Action Gateway is in [public preview](https://docs.digitalocean.com/platform/product-lifecycle/index.html.md#public-preview).

## 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 endpoint.

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 Endpoint

Open the [**Endpoints** page](https://cloud.digitalocean.com/managed-agents/action-gateway/endpoints) in the DigitalOcean Control Panel and begin creating an endpoint. Choose a name that is unique within your team and an actor ID. Names must contain 1-64 ASCII letters, digits, periods, underscores, or hyphens. For your own coding agent, use the [Control Panel default actor ID](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 endpoint should access, such as `user-123`.

The endpoint’s owner and actor cannot change across versions. Connections with that actor ID, owned by the same DigitalOcean user in the same team, supply the accounts the endpoint uses. Reuse the ID across endpoints 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.

The endpoint owner can use it and manage its versions. A team owner can list and delete another user’s endpoint, but cannot use it or manage its versions.

For workloads that use private tools or need `action_code` to access private resources, attach a VPC. VPC networking must be enabled for your team. The VPC must belong to your team in `ric1`. Omit the attachment for workloads that only need public tools.

Create the provider connection with the same owner, team, and actor ID as the endpoint. Configure its VPC and allowed destinations separately. The endpoint 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 endpoint version and connection. The enforced version 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 with an attachment. 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).

You can also add up to 1,000 characters of instructions. The MCP client receives these instructions during initialization. Do not include secrets, and do not use instructions as a replacement for permission rules.

For API requests, set `network.vpcUuid` to the VPC ID in the version configuration:

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

Action Gateway validates the VPC’s ownership and derives its region. Omit `network` for a version without an attachment. Copy the returned MCP URL unchanged.

## Choose Insights Consent

Insights recording is off by default unless your team requires logs. To enable it, select the recording checkbox under **Insights**. It records tool calls, prompts, responses, and tool outputs. Other team members can view this data, and ingestion charges apply. When enabled, choose whether to record logs and traces.

The following example shows the recording checkbox before it is selected:

![Insights recording checkbox, unchecked, with the data visibility and ingestion charge disclosure.](https://docs.digitalocean.com/screenshots/action-gateway/endpoint-insights-consent.5cce10772ac15841a0826b593d980a1f830cfe2858348109a7ed0430916687ca.png)

Team owners can require logs for every endpoint from **Endpoints**, then **Settings**. When required, individual endpoints cannot opt out of logs. Recording does not grant tool permissions. Consent applies to all endpoint versions and can be changed in the endpoint settings.

## Set Tool Access and Permissions

Choose a default action for the permission policy. The create form defaults to **Ask**:

- **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 version 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 endpoint’s actor ID before relying on them.

Select the tools or versioned Toolbelts the workload 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

Enable **Preload** for tools or Toolbelts the workload regularly needs. Their 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` in the version configuration. See [Preloading Tools](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/preloading-tools/index.html.md).

## Override Tool Output for the Endpoint

Select a tool and choose an **Output view** instead of **Full output**. The view overrides the fields returned by that tool under this version. 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.

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.

The override applies to every call to the tool under the version, including preloaded tools, `action_invoke`, and calls inside `action_code`. 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/endpoints/index.html.md#output-views).

## Create the Endpoint

Review the policy before creating the endpoint. Broad allow rules can permit writes, deletions, and other changes to connected accounts without a gateway prompt. The initial configuration becomes version 1.

## Connect and Inspect the Endpoint

Copy the endpoint’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 endpoint, in the same team. Calls through this URL use the head version’s tools and permissions. Use a read-only call to verify the intended access before running a workload that changes provider resources.

Open the endpoint to inspect its actor, versions, tools, policy, instructions, VPC attachment, and output-view bindings. To pin a client to a version, copy that version’s MCP URL instead of the endpoint URL. Copy URLs exactly as returned; do not derive them from an endpoint or version ID.

Use the endpoint settings to rename it or change Insights consent. Consent applies to every version, including pinned versions.

## Publish or Promote a Version

To change tool selection, policy, instructions, preloads, output views, or VPC attachment, publish a new version with the complete configuration from the endpoint’s **Versions** tab. This creates the new head. Clients using the endpoint URL use the new head; clients using a pinned version URL remain on that version. The endpoint URL hostname can change when the new head changes the VPC region. After changing the attachment, copy the latest returned URL and update the client if necessary. To use a different actor, create a separate endpoint.

To restore an older live configuration as the head, promote its version. Promotion copies that configuration into a new, higher-numbered version. For example, promoting version 1 after version 2 creates version 3. It does not change version 1 or restore an earlier Insights consent setting. The endpoint’s current consent applies to every version.

Each endpoint supports up to 100 live versions. Delete an older version to free capacity if needed before publishing or promoting. Deleted versions cannot be restored, and clients pinned to them lose access.

Do not publish a version 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.

## Delete Versions or an Endpoint

Deleting the head exposes the next highest live version as the head. If no live version remains, 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.

Deleting a version through the deprecated sessions API, `DELETE /v2/action-gateway/sessions/<session-urn>`, differs in one case: if it deletes the endpoint’s last live version, it also deletes the endpoint.

Deleting an endpoint deletes all its versions and stops access through its endpoint and version URLs. Head changes and deletions can take time to propagate: see [Endpoint Versions](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/endpoints/index.html.md#endpoint-versions) for the normal and stale-policy windows. Deletion does not undo provider actions or revoke 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).

## Manage the Default Endpoint

An authenticated user’s first request to `https://actions.do-ai.run/mcp` creates a default endpoint for that user and team. Its initial configuration selects all tools and asks for approval on every call. You can manage its versions, name, and Insights consent like those of other endpoints. See [Default Endpoints](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/endpoints/index.html.md#default-endpoints).

If you delete the default endpoint, the next request to the generic URL creates a new endpoint with a new ID and the initial configuration. Deleting all its versions does not create a replacement; publish a version to restore access. Renaming the endpoint does not change which endpoint the generic URL uses.

To identify your default endpoint, [list your endpoints using the API](#manage-endpoints-using-the-api) and find the entry with `is_default: true`. The marker identifies only the current caller’s default in the team. If `next_page_token` is nonempty, pass its value in the `page_token` query parameter to check the next page. Continue until you find the default or there are no more pages. Listing endpoints does not create a default; make a generic MCP or data-plane request first if you have not used one. Use the endpoint ID from the response to inspect it or publish a version.

You can also inspect the `X-Endpoint-Id` response header from a request to the generic URL or the data plane that sends neither `X-Endpoint-Id` nor `X-Session-Id`. The endpoint name alone does not identify it. The `X-Action-Gateway-Endpoint-Version` response header gives the resolved version ID, such as `<endpoint-id>.v2`. See [Choose the Target with Request Headers](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md#choose-the-target-with-request-headers).

## Manage Endpoints Using the API

Create a [DigitalOcean personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with the needed Action Gateway permissions and make it available locally as `DIGITALOCEAN_TOKEN`. Replace `<endpoint-id>` with the endpoint UUID and `<actor-id>` with the existing actor ID. See [Create an Endpoint Using the API](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md#create-a-session-using-an-sdk) for initial creation.

These requests manage endpoints through `https://api.digitalocean.com`. To search for or run an endpoint’s tools from your application, send [Data Plane API](https://docs.digitalocean.com/reference/api/reference/action-gateway-data-plane/index.html.md) requests to `https://actions.do-ai.run` with the endpoint UUID in `X-Endpoint-Id`. Optionally add the endpoint’s actor ID in `X-Actor-Id`; a different value returns `403`. See [Choose the Target with Request Headers](https://docs.digitalocean.com/products/managed-agents/action-gateway/how-to/connect-action-gateway/index.html.md#choose-the-target-with-request-headers).

To find endpoint IDs, list your endpoints:

```shell
curl "https://api.digitalocean.com/v2/action-gateway/endpoints" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"
```

Use `GET /v2/action-gateway/endpoints/<endpoint-id>` to inspect an endpoint, or `GET /v2/action-gateway/endpoints/<endpoint-id>/versions` to find its version IDs. Endpoint and version IDs also appear in create and publish responses.

Publish a complete version configuration with a request like this one:

```shell
curl -X POST "https://api.digitalocean.com/v2/action-gateway/endpoints/<endpoint-id>/versions" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "<actor-id>",
    "tools": ["digitalocean_size-list"],
    "policy": {
      "defaultAction": "deny",
      "rules": [
        {"tool": "action_search", "action": "allow"},
        {"tool": "action_invoke", "action": "allow"},
        {"tool": "digitalocean_size-list", "action": "allow"}
      ]
    }
  }'
```

The response includes `endpoint`, `version`, `mcp_url`, and `version_mcp_url`. Copy the returned URL appropriate for your client. Version creation is not a patch: include the complete settings you want to use.

Field names inside `policy`, `config`, and `network` use camel case, such as `defaultAction`, `preloadTools`, `outputViews`, `customInstructions`, and `vpcUuid`. Action Gateway stores `config` as supplied, so a misspelled key such as `preload_tools` is saved without an error but has no effect.

To promote a live version, replace `<version-id>` with its full ID, such as `<endpoint-id>.v1`, and send this request:

```shell
curl -X POST "https://api.digitalocean.com/v2/action-gateway/endpoints/<endpoint-id>/versions:promote" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"<version-id>"}'
```

To rename an endpoint or update Insights consent, send a patch containing at least one change. The following example changes its name and the endpoint-wide logs and traces settings:

```shell
curl -X PATCH "https://api.digitalocean.com/v2/action-gateway/endpoints/<endpoint-id>" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"support-agent-updated","insights":{"logs":true,"traces":false}}'
```

To delete a version, replace `<version-id>` with its full ID and send this request:

```shell
curl -X DELETE "https://api.digitalocean.com/v2/action-gateway/endpoint-versions/<version-id>" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"
```

To delete the endpoint and all its versions, send this request:

```shell
curl -X DELETE "https://api.digitalocean.com/v2/action-gateway/endpoints/<endpoint-id>" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"
```

See the [Action Gateway API reference](https://docs.digitalocean.com/products/managed-agents/action-gateway/reference/api/action-gateway/index.html.md) for the full requests and permissions.