DigitalOcean API (unofficial showcase)
POST/v2/action-gateway/mcp-servers

Register an MCP Server

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

13 body fields
serverRefstringrequired
Identifier for the server, unique within your team. Must match `^`[a-z]``[a-z0-9-]`{0,63}$`.
endpointstringrequired
HTTPS URL of the server's MCP endpoint. Its host must resolve only to public IP addresses. Required.
transportstringoptional
Optional. `streamable_http`, the default and only accepted value.
Allowed:streamable_httpDefault:streamable_http
credentialRefSourcestringoptional
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.
Allowed:nonesecretconnectionDefault:none
descriptionstringoptional
Optional description shown on the server's catalog card. At most 1024 characters.
credentialRefstringoptional
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_keystringoptional
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_idstringoptional
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_secretstringoptional
Required for `credentialRefSource` connection. Write-only; no response returns it.
oauth_authorize_urlstringoptional
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_urlstringoptional
Required for `credentialRefSource` connection: the OAuth token endpoint, under the same rules as `oauth_authorize_url`.
oauth_scopesarray<string>optional
Required for `credentialRefSource` connection: the scopes to request from each user, 1 to 64 of them.
oauth_authorization_ttl_secondsstringoptional
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.

7 status codes
200The MCP server was registered.
mcpServerobjectoptional
The MCP server.
400There was an error parsing the request body.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409The request could not be completed due to a conflict.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: There was an error parsing the request body. A 401 is returned: Authentication failed due to invalid credentials. A 409 is returned: The request could not be completed due to a conflict. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.