AI Workspace
1.0.0
References
Platform API

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:create`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:read`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:read`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:delete`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:undeploy`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:mcp_proxy:deployment:restore`, `ap:mcp_proxy:deployment:manage`, `ap:mcp_proxy:manage`

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