Docs

Connect an AI agent

Give an AI agent Confidential Cloud through the MCP server, signed in with OAuth or an agent key.

The MCP server at https://api.cloud.confidential.ai/mcp gives AI agents the cloud as tools. Each tool calls one operation of the REST API as the same person or key, so the same scopes, limits, rate limits, idempotency and audit log apply.

Add the server

The server speaks MCP over Streamable HTTP. In any MCP client that supports remote servers, add:

SettingValue
TransportStreamable HTTP
URLhttps://api.cloud.confidential.ai/mcp

Clients that read a JSON configuration take it in this shape:

{
  "mcpServers": {
    "confidential-cloud": {
      "type": "http",
      "url": "https://api.cloud.confidential.ai/mcp"
    }
  }
}

Sign in

With OAuth (recommended for people). The first time the client connects, the server answers 401 with a WWW-Authenticate header pointing at its protected resource metadata, and the client opens a browser for you to sign in at auth.confidential.ai, the same sign-in as the console. Pick the organization the agent should act in. Clients register themselves automatically, with a client ID metadata document or dynamic client registration.

The token acts as you, in that organization, with your role's permissions. A token issued for the MCP server works only there, and a token issued for the REST API does not work on the MCP server.

With an agent key (for agents that run without a person). Create an Agent key in the console under Settings > API keys, grant only the permissions the agent needs, and send it as a header:

{
  "mcpServers": {
    "confidential-cloud": {
      "type": "http",
      "url": "https://api.cloud.confidential.ai/mcp",
      "headers": { "Authorization": "Bearer cc_..." }
    }
  }
}

The MCP server accepts agent keys and no other kind of key.

The tools

A client sees only the tools its permissions allow, so a viewer sees no tool that changes anything.

ToolCallsDoes
list_locationsGET /v1/locationsWhere instances can run, and the TEEs each location offers
list_sizesGET /v1/sizesThe size catalog
get_capacityGET /v1/capacityHow many instances of each size one create could get now, in each location and TEE, for each way the size is sold
list_imagesGET /v1/imagesImages and their launch contracts
list_instancesGET /v1/instancesYour instances, filtered by label, status, TEE and more
get_instanceGET /v1/instances/{id}One instance; with waitFor, waits up to 45 seconds for a state
create_instancesPOST /v1/instancesCreates 1 to 16 instances
rename_instancePATCH /v1/instances/{id}Renames an instance, or turns its GPU metrics on or off
extend_instancePOST /v1/instances/{id}/extendMoves an instance's expiry later
start_instancePOST /v1/instances/{id}/startStarts a stopped instance
delete_instanceDELETE /v1/instances/{id}Deletes an instance; asks for its name as confirm
add_ingress_rule, remove_ingress_rulePOST, DELETE /v1/instances/{id}/ingressOpens and closes a port
add_dedicated_ipv4, remove_dedicated_ipv4POST, DELETE /v1/instances/{id}/dedicated-ipv4Gives an instance its own IPv4 address, or returns it to the shared one
get_limitsGET /v1/limitsWhat the agent may still create
get_usageGET /v1/usageWhat the org used each day, hour or month, by meter and location, and by inference model and key
list_usage_linesGET /v1/usage/linesWhat each instance used, by meter and month or hour
query_metrics, query_metrics_rangeGET /v1/prometheus/api/v1/query, /query_rangePromQL over your instances' metrics
list_reservation_offeringsGET /v1/reservation-offeringsPriced GPU offerings
request_gpu_reservationPOST /v1/reservationsRequests a GPU reservation, which waits for an owner's approval
list_reservations, get_reservationGET /v1/reservationsGPU reservations and their approval
withdraw_reservationDELETE /v1/reservations/{id}Withdraws a reservation request
request_gpu_capacityPOST /v1/capacity-requestsAsks for GPUs when no offering fits; holds and costs nothing
list_capacity_requests, get_capacity_requestGET /v1/capacity-requestsYour org's capacity requests
withdraw_capacity_requestDELETE /v1/capacity-requests/{id}Withdraws a capacity request
list_notification_channels, get_notification_channel, create_notification_channel, delete_notification_channel/v1/notification-channelsWhere alerts go: a Slack channel or a webhook
test_notification_channel, rotate_notification_channel_secretPOST /v1/notification-channels/{id}/test, /rotate-secretSends a test notification now, or gives a webhook channel a new signing secret
list_alert_subscriptions, create_alert_subscription, delete_alert_subscription/v1/alert-subscriptionsWhich instance events go to which channels
list_notificationsGET /v1/notificationsWhat was sent in the last 30 days, and how each delivery went
list_clusters, get_clusterGET /v1/clusters, /v1/clusters/{id}Your managed Kubernetes clusters, with their status and conditions
create_cluster, update_clusterPOST /v1/clusters, PATCH /v1/clusters/{id}Creates a cluster with its node pools, and upgrades or pauses it
delete_clusterDELETE /v1/clusters/{id}Deletes a cluster; asks for its name as confirm
get_cluster_cdsGET /v1/clusters/{id}/cdsThe state of a cluster's CDS, and what the c8s commands take to build and start it
upload_cluster_cds_launchPUT /v1/clusters/{id}/cds/launchUploads the two files c8s cds config new wrote, which start the cluster's CDS
list_node_pools, get_node_poolGET /v1/clusters/{id}/node-poolsA cluster's node pools
create_node_pool, update_node_pool, delete_node_pool/v1/clusters/{id}/node-poolsAdds, changes and deletes a node pool
search_docsSearches these docs, every field and every error code

The cluster tools are listed only for an org with managed Kubernetes. They sign nothing: you write a cluster's launch file and sign its decrees with your own key, on your own machine, and the agent uploads the files and follows the cluster. A cluster's credentials are never a tool: the token belongs in a kubeconfig, not in a model's context.

Organization and API key management, custom domains and reservation approvals are not tools: they stay with people in the console and the REST API.

Every tool carries MCP's hints, so a client can ask you before it runs anything that changes or destroys something. delete_instance also needs the instance's name (or id, if it has none) as confirm, and delete_cluster and delete_node_pool the cluster's or the pool's name, and each deletes nothing if it does not match.

What agents may do

An agent key, and an OAuth token issued to any client but the console, counts as an agent:

  • It is held to the limits set on its key, or for a token the organization's defaults for agents. get_limits returns them with what is in use.
  • A GPU reservation it requests waits for an owner of the organization to approve it in the console. The response's approval.url is the link to hand to a person; a request nobody decides within 72 hours is declined.
  • It never manages keys or people, and never approves anything.
  • Agent keys always expire, within 90 days (30 by default), and stop working when the person who made them leaves the organization.

A typical session

  1. list_images and list_sizes to pick a shape; get_capacity to check what fits now, and get_limits for your limits.
  2. create_instances with a fresh idempotencyKey, and the same key on any retry.
  3. get_instance with waitFor: "reachable", again until the instance is running and Reachable.
  4. Verify the instance before trusting it with anything: search_docs for "verify an instance", or see Verify an instance.
  5. delete_instance when done.

Errors come back as the API's problem documents (see Limits and errors), after a line that lists every invalid argument, so an agent can fix them all and retry.

On this page