Experimental
StartMcpGateway ensures a gateway exists for the sandbox.
POST
/v1/sandboxes/{sandbox}/mcp-gateway/start StartMcpGateway ensures a gateway exists for the sandbox.
Action: a lifecycle transition is not a representation a caller can PUT.
Connection and access
API connection and authentication guidance
https://connect.docker.com/sandboxes
—
The API base URL. Append the /v1 paths while preserving this URL's path prefix.
Use one of these alternatives. Requirements within an alternative apply together.
bearer
Parameters
sandbox
path
Required
The sandbox id.
Type:
string
All schema constraints and annotations
{
"type": "string"
}Request and responses
Request
application/json
Type:
object
StartMcpGatewayRequest ensures a sandbox gateway exists.
servers must be empty when gateway_url is set
gatewayUrl
Type:
string | null
gateway_url attaches read-only to a pre-existing shareable gateway when supported.
All schema constraints and annotations
{
"description": "gateway_url attaches read-only to a pre-existing shareable gateway when supported.",
"format": "uri",
"type": [
"string",
"null"
]
}servers
Type:
array
servers are initial server names for a backend-minted gateway.
Array item
Type:
string
All schema constraints and annotations
{
"minLength": 1,
"type": "string"
}All schema constraints and annotations
{
"description": "servers are initial server names for a backend-minted gateway.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
}static
Type:
boolean
static pins the requested server set and closes gateway-side discovery.
All schema constraints and annotations
{
"description": "static pins the requested server set and closes gateway-side discovery.",
"type": "boolean"
}All schema constraints and annotations
{
"additionalProperties": false,
"description": "StartMcpGatewayRequest ensures a sandbox gateway exists.\nservers must be empty when gateway_url is set",
"properties": {
"gatewayUrl": {
"description": "gateway_url attaches read-only to a pre-existing shareable gateway when supported.",
"format": "uri",
"type": [
"string",
"null"
]
},
"servers": {
"description": "servers are initial server names for a backend-minted gateway.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"static": {
"description": "static pins the requested server set and closes gateway-side discovery.",
"type": "boolean"
}
},
"title": "StartMcpGatewayRequest",
"type": "object"
}Response
200
Success
application/json
All constraints apply
Schema:
McpGateway
All schema constraints and annotations
{
"not": {
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}
}All schema constraints and annotations
{
"allOf": [
{
"$ref": "#/components/schemas/McpGateway"
},
{
"not": {
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}
}
]
}Response
202
Accepted. The resource is still progressing; read it or follow its events until completion.
application/json
All constraints apply
Schema:
McpGateway
state
· required
All schema constraints and annotations
{
"enum": [
"provisioning"
]
}All schema constraints and annotations
{
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}All schema constraints and annotations
{
"allOf": [
{
"$ref": "#/components/schemas/McpGateway"
},
{
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}
]
}Response
default
The structured Error body identifies the failure with a stable code and optional typed details.
application/json
Schema:
Error
Schema example
{
"code": "notFound",
"details": [],
"message": "sandbox not found"
}Referenced schemas
#/components/schemas/McpGateway
Complete operation contract
{
"description": "StartMcpGateway ensures a gateway exists for the sandbox.\nAction: a lifecycle transition is not a representation a caller can PUT.",
"operationId": "startMcpGateway",
"parameters": [
{
"description": "The sandbox id.",
"in": "path",
"name": "sandbox",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"description": "StartMcpGatewayRequest ensures a sandbox gateway exists.\nservers must be empty when gateway_url is set",
"properties": {
"gatewayUrl": {
"description": "gateway_url attaches read-only to a pre-existing shareable gateway when supported.",
"format": "uri",
"type": [
"string",
"null"
]
},
"servers": {
"description": "servers are initial server names for a backend-minted gateway.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"static": {
"description": "static pins the requested server set and closes gateway-side discovery.",
"type": "boolean"
}
},
"title": "StartMcpGatewayRequest",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/McpGateway"
},
{
"not": {
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}
}
]
}
}
},
"description": "Success"
},
"202": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/McpGateway"
},
{
"properties": {
"state": {
"enum": [
"provisioning"
]
}
},
"required": [
"state"
]
}
]
}
}
},
"description": "Accepted. The resource is still progressing; read it or follow its events until completion."
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The structured Error body identifies the failure with a stable code and optional typed details."
}
},
"security": [
{
"bearer": []
}
],
"summary": "StartMcpGateway ensures a gateway exists for the sandbox.",
"tags": [
"MCP gateways"
],
"x-sbx-authenticated-only": false,
"x-sbx-conditional-permissions": [],
"x-sbx-plane": "control",
"x-sbx-required-permissions": [
"mcpWrite"
],
"x-sbx-resource-response": {
"$ref": "#/components/schemas/McpGateway"
},
"x-sbx-serving-surface": "management"
}