Skip to content

MCP Proxy Deployments

MCP proxy deployment operations

Create and deploy a new deployment for MCP proxy

POST /mcp-proxies/{mcpProxyId}/deployments

Code samples

curl -X POST https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Creates an immutable deployment artifact for an MCP proxy and deploys it to a specified gateway. Each deployment targets a single gateway. The id parameter is the MCP proxy handle (identifier), not the UUID. The operation returns a transitional DEPLOYING status. Final success or failure will be reported asynchronously via the deployment's status and statusReason once the gateway acknowledges. Access is validated against the organization in the JWT token.

Payload

{
  "name": "v1.0-production",
  "base": "current",
  "gatewayId": "prod-gateway-01",
  "metadata": {}
}

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
body body DeployRequest true Deployment request with gateway ID, base reference, and metadata

Example responses

Asynchronous operation accepted; poll the deployment until status becomes DEPLOYED or FAILED.

{
  "deploymentId": "a73c85a1-d857-491e-a6b2-51dce05de7a2",
  "name": "v1.0-production",
  "gatewayId": "prod-gateway-01",
  "status": "DEPLOYING",
  "baseDeploymentId": "be6d8692-b9de-400e-b6c1-14db50154e27",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
201 Created MCP proxy deployed successfully DeploymentResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Response Headers

Status Header Type Format Description
201 Location string uri URL of the newly created resource.

Get deployments for an MCP proxy

GET /mcp-proxies/{mcpProxyId}/deployments

Code samples

curl -X GET https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Retrieves all deployment artifacts for a specific MCP proxy. The id parameter is the MCP proxy handle (identifier), not the UUID. Supports filtering by gateway handle and deployment status. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
gatewayId query string false Gateway ID consisting of the handle (unique slug identifier) of the Gateway to filter status by.
status query string false Filter deployments by status (DEPLOYED, UNDEPLOYED, DEPLOYING, UNDEPLOYING, FAILED, or ARCHIVED)
limit query integer false Maximum number of items to return per page.
offset query integer false Zero-based index of the first item to return.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway to filter status by.

Enumerated Values

Parameter Value
status DEPLOYED
status UNDEPLOYED
status DEPLOYING
status UNDEPLOYING
status FAILED
status ARCHIVED

Example responses

200 Response

{
  "count": 0,
  "list": [
    {
      "deploymentId": "a73c85a1-d857-491e-a6b2-51dce05de7a2",
      "name": "v1.0-production",
      "gatewayId": "prod-gateway-01",
      "status": "DEPLOYED",
      "baseDeploymentId": "be6d8692-b9de-400e-b6c1-14db50154e27",
      "metadata": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "statusReason": "string",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "total": 10,
    "offset": 0,
    "limit": 10
  }
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Deployments retrieved successfully DeploymentListResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Get deployment by ID

GET /mcp-proxies/{mcpProxyId}/deployments/{deploymentId}

Code samples

curl -X GET https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments/{deploymentId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Retrieves metadata for a specific deployment artifact including status, gateway association, and timestamps. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
deploymentId path string(uuid) true The UUID of the deployment

Example responses

200 Response

{
  "deploymentId": "a73c85a1-d857-491e-a6b2-51dce05de7a2",
  "name": "v1.0-production",
  "gatewayId": "prod-gateway-01",
  "status": "DEPLOYED",
  "baseDeploymentId": "be6d8692-b9de-400e-b6c1-14db50154e27",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "statusReason": "string",
  "updatedAt": "2019-08-24T14:15:22Z"
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Deployment metadata retrieved successfully DeploymentResponse
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Delete deployment

DELETE /mcp-proxies/{mcpProxyId}/deployments/{deploymentId}

Code samples

curl -X DELETE https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments/{deploymentId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Deletes a deployment artifact. Deletion is only allowed when the deployment is in UNDEPLOYED status. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
deploymentId path string(uuid) true The UUID of the deployment

Example responses

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

409 Response

{
  "status": "error",
  "code": "DEPLOYMENT_ACTIVE",
  "message": "Cannot delete an active deployment - undeploy it first."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
204 No Content Deployment deleted successfully None
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
409 Conflict Conflict. The deployment is still active and must be undeployed before deletion. Error
500 Internal Server Error Internal Server Error. Error

Undeploy deployment from gateway

POST /mcp-proxies/{mcpProxyId}/deployments/{deploymentId}/undeploy

Code samples

curl -X POST https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments/{deploymentId}/undeploy?gatewayId=string \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Undeploys an active deployment, stopping the MCP proxy from being served on the specified gateway. The deployment artifact remains in the system and can be restored later. Returns the updated deployment object with initial status UNDEPLOYING. Final status (UNDEPLOYED or FAILED) will be reported asynchronously via the deployment's status and statusReason once the gateway acknowledges.

The gatewayId query parameter is validated against the deployment's bound gateway to prevent unintended operations. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
deploymentId path string true UUID of the deployment to undeploy
gatewayId query string true Handle (URL-friendly slug) of the gateway (validated against deployment's bound gateway)

Example responses

Asynchronous operation accepted; poll the deployment until status becomes UNDEPLOYED or FAILED.

{
  "deploymentId": "a73c85a1-d857-491e-a6b2-51dce05de7a2",
  "name": "v1.0-production",
  "gatewayId": "prod-gateway-01",
  "status": "UNDEPLOYING",
  "baseDeploymentId": "be6d8692-b9de-400e-b6c1-14db50154e27",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Undeploy initiated successfully. Returns the deployment with initial status UNDEPLOYING. Poll status for final result. DeploymentResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
409 Conflict Conflict. The request conflicts with the current state of the resource. Error
500 Internal Server Error Internal Server Error. Error

Restore a previous deployment

POST /mcp-proxies/{mcpProxyId}/deployments/{deploymentId}/restore

Code samples

curl -X POST https://localhost:9243/api/v0.9/mcp-proxies/{mcpProxyId}/deployments/{deploymentId}/restore?gatewayId=string \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Initiates restoring a previous deployment (ARCHIVED or UNDEPLOYED) on the specified gateway. Returns the deployment with initial status DEPLOYING. Final success or failure will be reported asynchronously via the deployment's status and statusReason once the gateway acknowledges. The target deployment must not already be in DEPLOYED status.

The gatewayId query parameter is validated against the deployment's bound gateway to prevent unintended operations. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
mcpProxyId path string true Unique identifier of the MCP proxy
deploymentId path string true UUID of the deployment to restore (must be ARCHIVED or UNDEPLOYED)
gatewayId query string true Handle (URL-friendly slug) of the gateway (validated against deployment's bound gateway)

Example responses

Asynchronous operation accepted; poll the deployment until status becomes DEPLOYED or FAILED.

{
  "deploymentId": "a73c85a1-d857-491e-a6b2-51dce05de7a2",
  "name": "v1.0-production",
  "gatewayId": "prod-gateway-01",
  "status": "DEPLOYING",
  "baseDeploymentId": "be6d8692-b9de-400e-b6c1-14db50154e27",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Restore initiated successfully. Returns the deployment with initial status DEPLOYING. Poll status for final result. DeploymentResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
409 Conflict Conflict. The request conflicts with the current state of the resource. Error
500 Internal Server Error Internal Server Error. Error