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).

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.

Prerequisites

• Access to Action Gateway for your DigitalOcean team.
• For tools that access external accounts, connections to those accounts 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. Prepayment is not required for every tool.

Configure the Endpoint

Open the Endpoints page 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 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 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.

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:

{
  "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:

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.
• 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 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.

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.

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

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

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.

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

Manage Endpoints Using the API

Create a DigitalOcean personal access token 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 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 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.

To find endpoint IDs, list your endpoints:

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:

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:

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:

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:

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:

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

See the Action Gateway API reference for the full requests and permissions.