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:
| Setting | Value |
|---|---|
| Transport | Streamable HTTP |
| URL | https://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.
| Tool | Calls | Does |
|---|---|---|
list_locations | GET /v1/locations | Where instances can run, and the TEEs each location offers |
list_sizes | GET /v1/sizes | The size catalog |
get_capacity | GET /v1/capacity | How many instances of each size one create could get now, in each location and TEE, for each way the size is sold |
list_images | GET /v1/images | Images and their launch contracts |
list_instances | GET /v1/instances | Your instances, filtered by label, status, TEE and more |
get_instance | GET /v1/instances/{id} | One instance; with waitFor, waits up to 45 seconds for a state |
create_instances | POST /v1/instances | Creates 1 to 16 instances |
rename_instance | PATCH /v1/instances/{id} | Renames an instance, or turns its GPU metrics on or off |
extend_instance | POST /v1/instances/{id}/extend | Moves an instance's expiry later |
start_instance | POST /v1/instances/{id}/start | Starts a stopped instance |
delete_instance | DELETE /v1/instances/{id} | Deletes an instance; asks for its name as confirm |
add_ingress_rule, remove_ingress_rule | POST, DELETE /v1/instances/{id}/ingress | Opens and closes a port |
add_dedicated_ipv4, remove_dedicated_ipv4 | POST, DELETE /v1/instances/{id}/dedicated-ipv4 | Gives an instance its own IPv4 address, or returns it to the shared one |
get_limits | GET /v1/limits | What the agent may still create |
get_usage | GET /v1/usage | What the org used each day, hour or month, by meter and location, and by inference model and key |
list_usage_lines | GET /v1/usage/lines | What each instance used, by meter and month or hour |
query_metrics, query_metrics_range | GET /v1/prometheus/api/v1/query, /query_range | PromQL over your instances' metrics |
list_reservation_offerings | GET /v1/reservation-offerings | Priced GPU offerings |
request_gpu_reservation | POST /v1/reservations | Requests a GPU reservation, which waits for an owner's approval |
list_reservations, get_reservation | GET /v1/reservations | GPU reservations and their approval |
withdraw_reservation | DELETE /v1/reservations/{id} | Withdraws a reservation request |
request_gpu_capacity | POST /v1/capacity-requests | Asks for GPUs when no offering fits; holds and costs nothing |
list_capacity_requests, get_capacity_request | GET /v1/capacity-requests | Your org's capacity requests |
withdraw_capacity_request | DELETE /v1/capacity-requests/{id} | Withdraws a capacity request |
list_notification_channels, get_notification_channel, create_notification_channel, delete_notification_channel | /v1/notification-channels | Where alerts go: a Slack channel or a webhook |
test_notification_channel, rotate_notification_channel_secret | POST /v1/notification-channels/{id}/test, /rotate-secret | Sends a test notification now, or gives a webhook channel a new signing secret |
list_alert_subscriptions, create_alert_subscription, delete_alert_subscription | /v1/alert-subscriptions | Which instance events go to which channels |
list_notifications | GET /v1/notifications | What was sent in the last 30 days, and how each delivery went |
list_clusters, get_cluster | GET /v1/clusters, /v1/clusters/{id} | Your managed Kubernetes clusters, with their status and conditions |
create_cluster, update_cluster | POST /v1/clusters, PATCH /v1/clusters/{id} | Creates a cluster with its node pools, and upgrades or pauses it |
delete_cluster | DELETE /v1/clusters/{id} | Deletes a cluster; asks for its name as confirm |
get_cluster_cds | GET /v1/clusters/{id}/cds | The state of a cluster's CDS, and what the c8s commands take to build and start it |
upload_cluster_cds_launch | PUT /v1/clusters/{id}/cds/launch | Uploads the two files c8s cds config new wrote, which start the cluster's CDS |
list_node_pools, get_node_pool | GET /v1/clusters/{id}/node-pools | A cluster's node pools |
create_node_pool, update_node_pool, delete_node_pool | /v1/clusters/{id}/node-pools | Adds, changes and deletes a node pool |
search_docs | Searches 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_limitsreturns 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.urlis 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
list_imagesandlist_sizesto pick a shape;get_capacityto check what fits now, andget_limitsfor your limits.create_instanceswith a freshidempotencyKey, and the same key on any retry.get_instancewithwaitFor: "reachable", again until the instance isrunningandReachable.- Verify the instance before trusting it with anything:
search_docsfor "verify an instance", or see Verify an instance. delete_instancewhen 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.