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 can call tools on a private network without exposing the provider’s endpoint to the public internet. Configure a connection with the provider’s VPC and allowed destinations, then use that connection from a session.

VPC networking must be enabled for your team and is available in ric1. Private MCP discovery also requires an enabled discovery route in that region. If VPC networking is unavailable for your team, contact support.

How Private Tools Connect

Start with an MCP server running in your VPC. Register its endpoint and VPC as a custom provider so Action Gateway knows where to discover its tools.

Next, create a connection for the application identity that needs those tools. You name this identity with an actor ID, such as example-private-tools-user. The connection specifies the VPC, destination hosts, and ports that calls can use. For a private MCP server, the connection must select the server’s exact VPC and allow its endpoint.

Create a session with the same actor ID to use that connection. The session and connection must belong to the same DigitalOcean user and team. Your MCP client connects to the session’s returned URL, and Action Gateway sends private tool calls through the connection’s VPC. The client does not need direct access to that VPC.

The session also has its own VPC attachment. This chooses where action_code can access private resources and determines the region for private tool calls. Its region must match the connection’s region, but their VPC IDs can differ. For your first provider, use the same VPC for the server, connection, and session.

Each provider call uses its connection’s network settings, including calls made from action_code. Public connections continue to use public networking.

Check the Requirements

• Use a VPC owned by your DigitalOcean team in ric1.
• Create the connection and session as the same DigitalOcean user, in the same team, with the same actor ID. VPC membership alone does not authorize another user’s connection.
• Use a provider that supports VPC connections. The connection form shows Reach a service in a VPC only when the provider and your access support it.
• Allow the provider’s destination host and port on the connection. The destination list permits traffic; it does not change the provider’s endpoint.
• Make the service reachable from the selected VPC. Its firewall, listening port, TLS configuration, and authentication still apply.
• Keep private calls in the session’s region and use its returned MCP URL unchanged. Action Gateway does not support cross-region private calls.

A private MCP server can use an API key, an OAuth connection, or no upstream authentication. Its authentication method is separate from network access: even an unauthenticated server needs an active connection to grant access through the VPC.

Use HTTPS for authenticated MCP servers. Unauthenticated servers can use HTTP or HTTPS with a hostname or IP address, on public or private networks. HTTP does not encrypt tool inputs or results, so use it only when that is appropriate for your service. Private endpoints must still satisfy the connection’s destination restrictions.

Prepare a Private MCP Server

To connect a first provider, use an existing MCP server in your VPC that supports Streamable HTTP and exposes a read-only tool. The examples below use an unauthenticated server with an echo tool at http://10.20.0.10:8080/mcp. Replace the address, port, and tool name with those from your server.

Find the VPC’s ID on the VPC page. Use that ID wherever the examples show <vpc-uuid>. Use example-private-tools-user as an example actor ID, or choose a stable ID for your application.

You can register the server and create its connection in the Control Panel or through the API. Use the same DigitalOcean user and team for the provider connection and session.

Connect the Provider Using the Control Panel

1. Go to the Tool Providers page and click Add custom provider.
2. Enter example-private-tools as the Server name and your private MCP endpoint as the Endpoint URL. Select None under Authentication for this unauthenticated example.
3. Select Reach this server in a VPC, choose the Server VPC, and click Connect and discover tools.
4. In the connection window, enter example-private-tools-user as the Actor ID. Review VPC Attachment, Destination host, and Destination port, then click Connect. Discovery uses this actor’s connection.
5. On Server tools, enable the read-only tool you intend to test and click Add custom provider.

Continue with Attach and Connect a Session. For API-key or OAuth setup, see Add a Custom Tool Provider.

Connect the Provider Using the API

The request examples use the API at https://api.digitalocean.com and a DigitalOcean token belonging to the user and team that own the connection and session. Set DIGITALOCEAN_TOKEN privately in your local environment. Do not put the token in an agent conversation or source file.

Register the Private Provider

Create a local file named private-provider.json with this registration request body:

{
  "server_ref": "example-private-tools",
  "endpoint": "http://10.20.0.10:8080/mcp",
  "transport": "streamable_http",
  "credential_ref_source": "none",
  "network": {
    "vpc": {
      "vpc_uuid": "<vpc-uuid>"
    }
  }
}

After replacing <vpc-uuid> and the endpoint, run this command in your local terminal:

curl --fail-with-body \
  --request POST \
  --url https://api.digitalocean.com/v2/action-gateway/mcp-servers \
  --header "Authorization: Bearer ${DIGITALOCEAN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data @private-provider.json

For the remaining API steps, use the same host and headers with the stated method, path, and JSON body.

The server’s network identifies its VPC. Registration leaves the server pending discovery; create its connection next.

For an authenticated server, use HTTPS and set credential_ref_source to secret for an API key or connection for OAuth. Supply the corresponding authentication settings.

Create the Private Connection

For an unauthenticated private MCP connection, set provider to the server_ref you registered. Action Gateway resolves it within your team. Use example-private-tools for this server.

Send a POST /v2/action-gateway/connections request with this JSON body. This endpoint names the actor field user_id; use the same value as actor_id when creating the session:

{
  "provider": "example-private-tools",
  "user_id": "example-private-tools-user",
  "credential": {
    "none": {}
  },
  "network": {
    "vpc": {
      "vpc_uuid": "<vpc-uuid>",
      "destinations": [
        {
          "host": "10.20.0.10",
          "port": 8080
        }
      ]
    }
  }
}

credential.none selects a connection with no upstream credential. The destination permits calls to the private server at 10.20.0.10 on port 8080. For hostname destinations, you can also restrict the IP ranges that DNS can return.

Check that the returned connection is active and its VPC matches the registered server. This connection stores no provider secret and has no OAuth consent step. It still controls access to the private endpoint.

For providers with credentials, create a connection with the appropriate authentication method and the same VPC and destination settings.

Discover and Enable the Private Tools

Send a POST /v2/action-gateway/mcp-servers/example-private-tools/resync request with the connection’s actor ID:

{
  "user_id": "example-private-tools-user"
}

Discovery uses that actor’s connection to reach the server through its registered VPC. If the response reports pending, check GET /v2/action-gateway/mcp-servers/example-private-tools until discovery finishes. Check mcpServer.syncStatus and mcpServer.syncError before continuing.

Read GET /v2/action-gateway/mcp-servers/example-private-tools/tools and inspect the returned tool names. Use the returned tool slug rather than constructing it yourself.

To enable only the read-only tool, send a PUT /v2/action-gateway/mcp-servers/example-private-tools/tools request. Replace <read-only-tool-slug> with that tool’s returned slug:

{
  "user_id": "example-private-tools-user",
  "enabled_tool_slugs": ["<read-only-tool-slug>"]
}

This list replaces the enabled selection for the server. Tools omitted from it are disabled. Verification can contact the server again, so keep the actor’s connection active.

Attach and Connect a Session

Go to the Sessions page and click Create session. Enter a session name and the actor ID example-private-tools-user. Under VPC Attachment, select the same VPC you used for the connection and server.

The session configuration keeps the actor ID and VPC attachment together. This example shows a selected VPC with its name and ID replaced:

Choose Selected tools, select the read-only tool you enabled, and set the permission policy for your workload. Use Ask with an approval-capable client, or allow only the read-only tool you intend to test. Create the session and copy its returned MCP URL.

To create the session through the API, set network.vpc_uuid to the VPC ID:

{
  "name": "example-private-tools",
  "actor_id": "example-private-tools-user",
  "tools": ["<read-only-tool-slug>"],
  "network": {
    "vpc_uuid": "<vpc-uuid>"
  }
}

Send this body to POST /v2/action-gateway/sessions. Omitting the permission policy uses the default approval policy. Connect your MCP client using the returned MCP URL and authenticate as the session’s owner in the same team.

Ask the client to find the private provider’s read-only tool, inspect its input schema, and call it with a non-sensitive test value. For an echo tool, check that the result matches the value you sent.

Review the Configuration

The completed setup connects the server, actor, and session as follows:

Resolve Private Connection Errors

If a private call fails, check the settings that control that call:

• For a VPC mismatch, compare the connection’s VPC ID with the server’s registered VPC ID. For a session-region mismatch, create a replacement session attached to a VPC in the connection’s region.
• If the endpoint is not authorized, add its exact host and port to the connection’s destinations. Enter only the host, not a URL or path. Use 443 for HTTPS or 80 for HTTP when the endpoint has no explicit port.
• If access to a destination is denied, check the allowed IP ranges and the service’s network rules. Use canonical CIDRs, such as 10.20.0.0/24, or a single-address range such as 10.20.0.10/32.
• If discovery reports that private MCP discovery is not configured, the regional discovery route is unavailable. Contact support; changing credentials or registering another provider does not enable it.
• If authorization is required, check the connection’s owner, actor ID, status, and authentication method. A none connection must still exist and be active.

A private server does not fall back to public networking when its connection is missing, revoked, or mismatched. Register a new server to change a public registration to a private one. Create a replacement session to change its VPC attachment.