Skip to main content

Connect Environments with API Key

After creating and delivering API Keys for environments, you need to connect CloudBase to your AI Agent (AI development tool) so that the Agent can directly operate cloud resources. Depending on how the Agent runs, there are two common scenarios:

ScenarioAgent formTypical productsConnection method
Connect a client AgentRuns locally on the user's machineWorkBuddy, Claude Code, Codex, etc.User configures CloudBase MCP with the API Key
Connect a cloud AgentRuns on the platform cloudLovable, Bolt.new, etc.Platform service configures the API Key and calls MCP or API

Connect a Client Agent​

A client Agent runs on the user's own computer, such as WorkBuddy, Claude Code, Codex, etc. After the platform creates environments and issues API Keys, you need to let users configure CLOUDBASE_ENV_ID and CLOUDBASE_API_KEY into CloudBase MCP through secure channels.

There are two main ways to connect a client Agent:

Method 1: Deliver configuration via site messages, emails, and other channels​

Suitable for scenarios where users have some technical capability and can edit Agent configuration themselves.

  1. The platform provides users with their exclusive environment ID and API Key through secure channels such as site messages and emails.
  2. Users install CloudBase MCP in their Agent tool.
  3. Users fill in the following environment variables according to the MCP configuration format of the Agent tool:
{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "CLOUDBASE_API_KEY": "<API Key delivered by the platform>",
        "CLOUDBASE_ENV_ID": "<environment ID delivered by the platform>"
      }
    }
  }
}
  1. Users restart or refresh the Agent, and they can use CloudBase MCP to operate the corresponding environment.

Method 2: Complete configuration via the MCP authorization page​

Suitable for scenarios where you want to lower the configuration barrier and let users complete guided integration in the Agent tool.

  1. The platform sends users the installation instructions or entry point of CloudBase MCP through secure channels such as site messages and emails.
  2. Users install CloudBase MCP in their Agent tool.
  3. Users open the authorization page provided by MCP and fill in the environment ID and API Key delivered by the platform.
  4. After authorization, MCP automatically saves the connection configuration, and users can operate the corresponding environment without manually editing the MCP configuration file.

The specific authorization page and configuration flow depend on the implementation of the Agent tool. The platform can also integrate the above flow into its own product to provide a unified installation guide and credential configuration entry.

Other connection methods​

In addition to the above methods, the platform can also provide one-click installation, pre-configured installation packages, enterprise software distribution, or its own desktop integration, depending on the capabilities of the Agent tool. Regardless of the method, the final goal is to configure the user-exclusive CLOUDBASE_ENV_ID and CLOUDBASE_API_KEY into CloudBase MCP.

  • WorkBuddy: has a built-in CloudBase connector that can be enabled with one click through the Connector button in the conversation interface. See WorkBuddy configuration guide.
  • Claude Code, Codex, etc. : install CloudBase MCP in the corresponding IDE and configure the environment variables as supported by the tool. See Connect CloudBase MCP for details.
Security tips

api_key has full read/write permissions on the environment's own data. API Keys are only for local MCP configuration on the user side or platform server-side configuration, do not write them into business frontends, application code repositories, or public channels. The platform should distribute them through secure channels and it is recommended to rotate them regularly. A maximum of 5 keys can be created per environment.

Connect a Cloud Agent​

A cloud Agent runs in the platform's cloud service, such as platforms that "generate applications from natural language" like Lovable and Bolt.new. In this scenario, the platform itself is responsible for purchasing the package, creating and allocating environments, and the cloud Agent completes the creation and management of cloud resources by calling CloudBase MCP (hosted mode) or CloudBase API.

Recommended flow:

  1. The platform purchases the package and allocates environments: the platform purchases the Platform Edition package, calls CreateEnv to create exclusive environments for users, and maintains the mapping between user IDs and environment IDs. See Purchase and Initialization and Create Environments.
  2. Get environment API Keys: the platform calls CreateApiKey to create API Keys for user environments, and securely stores the API Keys and environment IDs on the platform server side. See Manage API Keys.
  3. Connect the cloud Agent to CloudBase:
  4. Resource creation and management: the cloud Agent creates databases, deploys cloud functions, configures domains, and more in the user environment.

Other Credential Methods​

In Platform Edition scenarios, the environment API Key is the most recommended connection method. If you need to use other credential methods (such as custom auth codes or temporary keys), see Connect environments with other credentials and adapt them to the Platform Edition permission model (API Keys are only granted access to the environment's own data).

Next Steps​

After integration, you can do the following based on business needs:

  • Query the credit usage of each environment for cost analysis (Platform Edition provides environment-level usage query APIs, supporting queries by time range and environment ID)
  • Manually suspend / start a single environment according to business strategy to control user usage status