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

Usage

client.mcp_servers.create(
    body={
        "serverRef": "docs",
        "endpoint": "https://mcp.example.com/mcp",
        "transport": "streamable_http",
        ...,
    },
)

Description

Registers a remote MCP server for your team, using the streamable HTTP transport. The server starts with syncStatus pending and no tools: discover its tools with POST .../mcp-servers/{server_ref}/resync, then choose which to enable with PUT .../mcp-servers/{server_ref}/tools. The endpoint must be HTTPS and resolve only to public IP addresses. The number of servers per team is limited (10 by default); registering beyond it returns 429. Returns 409 when serverRef is already in use.

Parameters

serverRef string required

Example: docs

Identifier for the server, unique within your team. Must match ^[a-z]`[a-z0-9-]{0,63}$`.

endpoint string required

Example: https://mcp.example.com/mcp

HTTPS URL of the server's MCP endpoint. Its host must resolve only to public IP addresses. Required.

transport string optional

Example: streamable_http

Optional. streamable_http, the default and only accepted value.

Default: streamable_http

credentialRefSource string optional

How requests to the server authenticate: none (the default), secret, or connection. With secret, the value from credentialRef or api_key is sent in the Authorization header, prefixed with "Bearer " unless it already contains a space.

One of: none, secret, connection

Default: none

description string optional

Example: Internal documentation search.

Optional description shown on the server's catalog card. At most 1024 characters.

Max length: 1024

credentialRef string optional

For credentialRefSource secret: a reference to a secret your team stores with DigitalOcean. Must match ^[A-Za-z0-9]`[A-Za-z0-9:/_.-]{0,254}$. Set exactly one of credentialRef and api_key`.

api_key string optional

Example: sk_live_example

For credentialRefSource secret: the key or token itself. DigitalOcean stores it; it is write-only and no response returns it. Set exactly one of credentialRef and api_key.

oauth_client_id string optional

Required for credentialRefSource connection: the client ID of your team's OAuth client for the server. Each user of the server then authorizes individually.

oauth_client_secret string optional

Required for credentialRefSource connection. Write-only; no response returns it.

oauth_authorize_url string optional

Required for credentialRefSource connection: the OAuth authorization endpoint. It must use the endpoint's scheme and port, on the endpoint's host or another host under the same registrable domain.

oauth_token_url string optional

Required for credentialRefSource connection: the OAuth token endpoint, under the same rules as oauth_authorize_url.

oauth_scopes array of strings optional

Example: []

Required for credentialRefSource connection: the scopes to request from each user, 1 to 64 of them.

oauth_authorization_ttl_seconds string optional

Example: 86400

How long, in seconds, a user's authorization may be reused before they must consent again. Optional;
0 means 30 days, and the maximum is 100 years.

Authorizations are not refreshed automatically, so this window, not the provider's token lifetime,
decides how often a user is sent back through consent. Set it no longer than the provider's own
token lifetime, so the prompt arrives before a tool call fails against an expired token.

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "serverRef": "docs",
  "endpoint": "https://mcp.example.com/mcp",
  "credentialRefSource": "secret",
  "api_key": "sk_live_example",
  "description": "Internal documentation search."
}

resp = client.mcp_servers.create(body=req)

Response Example

{
  "mcpServer": {
    "serverRef": "docs",
    "endpoint": "https://mcp.example.com/mcp",
    "transport": "streamable_http",
    "credentialRefSource": "secret",
    "credentialRef": "action-infra/tool-credentials/mcp/docs/3f5b2c1e-9a7d-4e8b-b6c4-2d1f0e9a8b7c",
    "syncStatus": "pending",
    "syncError": "",
    "lastSyncedAt": "",
    "protocolVersion": "",
    "toolCount": 0,
    "createdAt": "2026-09-20T15:00:00Z",
    "updatedAt": "2026-09-20T15:00:00Z",
    "description": "Internal documentation search.",
    "oauth_authorize_url": "",
    "oauth_scopes": [],
    "oauth_authorization_ttl_seconds": "0"
  }
}

More Information

See /v2/action-gateway/mcp-servers in the API reference for additional detail on responses, headers, parameters, and more.