Connect an AI client to Cloudgate

You need to be an Owner or Admin of the Organization to create an Agent. The steps below use the fictional Northwind Labs organization, its storefront Project and the web Service in production. What an Agent is, and why it is not you, is in the MCP overview.

Create an Agent

1. Open the Agents settings

   In the console, open Settings, then Agents. Each Agent is one row, with its role, what it reaches, its keys and when a client last connected.

   cloudgate.octabyte.app/settings/agents

   

2. Name it and choose a role

   Press Create an Agent. Under Name, say what it is for, such as deploy-bot: it is how the audit log names it. Under Role, pick:

   • Reader (the default) to let it read Services, Environments, Deployments, Deployment logs and Domains, and change nothing;
   • Operator to let it also deploy, start, stop and cancel Deployments of what it is granted;
   • Caller only for an app that calls your AI models through the Gateway. A Caller gets no MCP tools.

   A Reader can still call request_plan, which spends the write budget. See guard rails.

3. Grant what it may reach

   Under Access, tick the Projects, Environments or Services it may reach. Access starts empty, and granting a Service grants its Environment and Project too. For an agent that fixes the storefront, tick web in production of storefront, nothing more. You can save with nothing ticked and grant later with Manage access.

4. Choose when the key expires, and copy it

   Under First key expires, pick 30 days, 90 days (the default) or a year. There is no never-expiring agent key. Press Create Agent and copy the key: this is the only time it is readable. The Connect panel appears under it.

Add Cloudgate to your client

The Connect panel shows one tab per client, with your console’s address already filled in. The address is your console’s origin plus /mcp: https://cloudgate.octabyte.app/mcp on the Hosted instance, and here https://cloud.northwind.example/mcp for a self-hosted one.

cloudgate.octabyte.app/settings/agents

{
  "mcpServers": {
    "cloudgate": {
      "type": "http",
      "url": "https://cloud.northwind.example/mcp",
      "headers": { "Authorization": "Bearer ${CLOUDGATE_AGENT_KEY}" }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cloudgate-agent-key",
      "description": "Cloudgate agent key",
      "password": true
    }
  ],
  "servers": {
    "cloudgate": {
      "type": "http",
      "url": "https://cloud.northwind.example/mcp",
      "headers": { "Authorization": "Bearer ${input:cloudgate-agent-key}" }
    }
  }
}

{
  "mcpServers": {
    "cloudgate": {
      "url": "https://cloud.northwind.example/mcp",
      "headers": { "Authorization": "Bearer ${env:CLOUDGATE_AGENT_KEY}" }
    }
  }
}

[mcp_servers.cloudgate]
url = "https://cloud.northwind.example/mcp"
bearer_token_env_var = "CLOUDGATE_AGENT_KEY"

{
  "url": "https://cloud.northwind.example/mcp",
  "headers": { "Authorization": "Bearer <agent key>" }
}

Set the variable before you start the client, for example in your shell profile:

export CLOUDGATE_AGENT_KEY=<agent key>

Check that it is connected

Ask the agent “list my Cloudgate Projects”. It should call list_projects and answer with the Projects you granted, and the Agent’s row in the console changes Last connected from “No client has connected yet” to a time. If it does not:

More refusals, with what each means, are in guard rails.

Give an agent access to your repository

Cloudgate’s grant reaches Projects, Environments and Services, never your git provider. An agent that pushes a fix and then asks for a requested preview of its branch needs write access to the repository the Application builds from. Give the AI tool that access with your git provider, scoped as you see fit; nothing in Cloudgate asks for it.

Rotate or revoke a key

Press Add key on the Agent’s row, put the new key in the client, then Revoke the old one. The Agent’s other keys keep working throughout. The Connect action on the row shows the client configuration again, but never a key. The Agents guide covers suspending and deleting an Agent, and the audit log shows every call each key made.