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

Action Gateway endpoints provide MCP URLs with tools and permissions for an actor. Add a URL to your MCP client and authenticate with DigitalOcean to use those tools. Use your automatic default endpoint, or create a named endpoint with Python, TypeScript, or the API when you need a separate configuration.

For a guided setup with a read-only first call, use the Action Gateway Quickstart. Harness Runtime integration is documented separately in Connect Action Gateway to Harness Runtime.

Prerequisites

• Access to Action Gateway.

Some tools, including Exa web search and web fetch, require a positive prepaid balance. Prepayment is not required for every tool.

Connect an External MCP Client

Use a client that supports remote Streamable HTTP MCP servers, such as a coding agent, OpenClaw, Hermes, or ChatGPT. Authentication setup and support for approval prompts depend on the client.

Choose an MCP URL:

Register the URL as a Streamable HTTP MCP server in your client. Authenticate through the client as the DigitalOcean user who owns the endpoint, in the same team. Restart the client or reload its MCP configuration if required, then confirm the server connects. Copy returned URLs exactly. If a new head changes the VPC region, the endpoint URL hostname can change, so copy the latest URL and update the client if needed.

In the following commands, replace <action-gateway-mcp-url> with your chosen URL.

For Codex, add the server and start browser sign-in:

codex mcp add action-gateway --url "<action-gateway-mcp-url>"
codex mcp login action-gateway

For Claude Code, add the server:

claude mcp add --transport http action-gateway "<action-gateway-mcp-url>"

In Claude Code, run /mcp, select action-gateway, and follow the browser sign-in prompts.

This signs the client in to Action Gateway, not to GitHub, Linear, or another external service. For tools that access those accounts, create provider connections using the endpoint’s actor ID. You can connect accounts later without changing the MCP URL.

For calls that use ask, your client must support gateway approval. A connected MCP server does not by itself guarantee inline approval prompts.

Create an Endpoint Using an SDK or the API

Create a DigitalOcean personal access token authorized for Action Gateway in your team and make it available locally as DIGITALOCEAN_TOKEN. Do not paste the token into an agent conversation or commit it to source control. Replace <actor-id> with the actor ID for this endpoint.

The following examples create an endpoint with one selected, read-only tool and explicit permissions for search and invocation. Each prints the endpoint’s MCP URL.

pip install --upgrade pydo

import os

from pydo.action_gateway import ActionGatewayClient

client = ActionGatewayClient(token=os.environ["DIGITALOCEAN_TOKEN"])
endpoint = client.endpoints.create(
    "support-agent",
    actor_id="<actor-id>",
    tools=["digitalocean_size-list"],
    permissions={
        "default_action": "deny",
        "rules": [
            {"tool": "action_search", "action": "allow"},
            {"tool": "action_invoke", "action": "allow"},
            {"tool": "digitalocean_size-list", "action": "allow"},
        ],
    },
)
print(endpoint.mcp_url)

python action_gateway_endpoint.py

npm install @digitalocean/dots @microsoft/kiota-http-fetchlibrary

import {
  createDigitalOceanClient,
  DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";

const client = createDigitalOceanClient(
  new FetchRequestAdapter(
    new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!),
  ),
);
const response = await client.v2.actionGateway.endpoints.post({
  name: "support-agent",
  version: {
    actorId: "<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" },
      ],
    },
  },
});
if (!response?.mcpUrl) {
  throw new Error("The endpoint response did not include an MCP URL.");
}
console.log(response.mcpUrl);

curl -X POST "https://api.digitalocean.com/v2/action-gateway/endpoints" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "version": {
      "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"}
        ]
      }
    }
  }' | jq -r '.mcp_url'

The endpoint URL follows the head version. To pin a client to the created version, copy version_mcp_url from the API response, endpoint.version_mcp_url in PyDo, or versionMcpUrl from the DoTs response instead. See the Action Gateway API reference for endpoint operations. Existing session integrations can continue to use their session URLs.

Choose the Target with Request Headers

Endpoint and version MCP URLs already identify their target. Requests to the generic MCP URL, https://actions.do-ai.run/mcp, and to the Action Gateway Data Plane API at https://actions.do-ai.run choose their target with a request header:

• X-Endpoint-Id: The endpoint UUID. The request uses the endpoint’s current head version.
• X-Session-Id: A legacy session UUID. For a pinned endpoint version, use the session UUID at the end of the version’s mcp_url, not the composite version ID.

Send one of these headers, not both. A request with both, or with a malformed or repeated X-Endpoint-Id, returns 400. An endpoint that does not exist, belongs to another user or team, or has no live version returns 404. A request with neither header uses your default endpoint. If no default endpoint is available for your account, it returns 403.

X-Actor-Id is optional. It does not select an actor or connections; those come from the endpoint’s or session’s actor ID. When you send it, Action Gateway checks that it equals that actor ID. A different value, or any value for a target with no actor, returns 403 with the message The session is not bound to the request's actor. Send it from an application that serves several users, set to the actor ID of the user the request is for, so a request sent to the wrong endpoint fails before any tool runs.

Responses that resolve an endpoint’s head, through X-Endpoint-Id, the default endpoint, or an endpoint MCP URL, include X-Action-Gateway-Endpoint-Version with the ID of the version that served the request, such as <endpoint-id>.v3. When the request used your default endpoint, the response also includes X-Endpoint-Id with that endpoint’s UUID.

For example, the following request searches the head version of an endpoint for <actor-id> and prints the response headers. Replace <endpoint-id> with the endpoint UUID and <actor-id> with its actor ID:

curl --include -X POST "https://actions.do-ai.run/tools/search" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Endpoint-Id: <endpoint-id>" \
  -H "X-Actor-Id: <actor-id>" \
  -d '{"queries":[{"use_case":"List available DigitalOcean Droplet sizes"}],"limit":3}'

Find Tools in a Large Catalog

Use action_search to discover tools within the endpoint version’s selected catalog, then action_invoke to run one with its documented arguments. Search results do not expand permissions.

To access a third-party provider, authorize a connection for the endpoint’s actor. To reuse a versioned collection of tools, create a Toolbelt.