Skip to main content

Connect Environments with API Key

After creating and delivering an API Key for an environment, you need to connect CloudBase to your AI Agent (AI development tool) so that the Agent can directly operate cloud resources. Depending on the Agent's runtime form, there are two common scenarios:

ScenarioAgent formTypical productsIntegration method
Client Agent integrationRuns on the user's local machineWorkBuddy, Claude Code, Codex, etc.Users obtain the API Key and configure the CloudBase MCP
Cloud Agent integrationRuns in the platform cloudLovable, Bolt.new, etc.The platform service configures the API Key and calls MCP or APIs

Client Agent Integration​

Client Agents run on the user's own computer, such as WorkBuddy, Claude Code, Codex, etc. After the platform completes environment creation and API Key issuance, it needs to let users configure CLOUDBASE_ENV_ID and CLOUDBASE_API_KEY into the CloudBase MCP through a secure method.

There are two main ways to integrate client Agents:

Method 1: Distribute configuration through in-site messages, email, etc.​

Suitable for scenarios where users have a certain level of technical ability and can edit Agent configurations themselves.

  1. The platform provides users with their exclusive environment ID and API Key through secure channels such as in-site messages and email.
  2. Users install the CloudBase MCP in their Agent tool.
  3. Users fill in the following environment variables according to the MCP configuration format of their 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 to use the CloudBase MCP to operate the corresponding environment.

Method 2: Complete configuration through the MCP authorization page​

Suitable for scenarios where you want to lower the configuration barrier and guide users to complete integration within the Agent tool.

  1. The platform sends users the installation instructions or entry point of the CloudBase MCP through secure channels such as in-site messages and email.
  2. Users install the CloudBase MCP in their Agent tool.
  3. Users open the authorization page provided by the MCP and fill in the environment ID and API Key delivered by the platform.
  4. After authorization, the 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 Integration Methods​

In addition to the above methods, the platform can also provide one-click installation, pre-configured installation packages, enterprise software distribution, or self-developed desktop integration depending on the Agent tool's capabilities. Regardless of the method used, ultimately the user's exclusive CLOUDBASE_ENV_ID and CLOUDBASE_API_KEY should be configured into the CloudBase MCP.

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

api_key has full administrator permissions on the environment. The API Key is only used for user-local MCP or platform server-side configuration; do not write it into business frontends, application code repositories, or public channels. The platform should distribute it through secure channels, and it is recommended to rotate it regularly, with a maximum of 5 keys per environment.

Cloud Agent Integration​

Cloud Agents run in the platform's cloud services, such as Lovable and Bolt.new, platforms that "generate applications from natural language". In this scenario, the platform itself is responsible for creating and allocating environments, and the cloud Agent creates and manages cloud resources by calling CloudBase MCP (hosted mode) or CloudBase APIs.

Recommended flow:

  1. Platform creates and allocates environments: the platform calls CreateEnv to create an exclusive environment for the user and maintains the mapping between user IDs and environment IDs; see Create environments.
  2. Get environment API Key: the platform calls CreateApiKey to create an API Key for the user environment and securely stores the API Key and environment ID on the platform server side; see Get environment API Key.
  3. Cloud Agent connects to CloudBase:
  4. Resource creation and management: the cloud Agent creates databases, deploys cloud functions, configures domains, etc. in the user environment; see Manage environment resources.

Other Credential Methods​

The above flow uses API Key as the environment credential, which is also the recommended method in platform integration scenarios. If your scenario requires users to complete a one-time authorization login through their own domain, or requires the platform server side to control the credential lifecycle, CloudBase also supports the following two credential methods:

  • Custom auth code: enterprises build their own authorization page to proxy the device code flow; users complete login entirely under their own domain without being aware of Tencent Cloud
  • Temporary keys: issue policy-limited temporary keys through STS GetFederationToken, suitable for scenarios where the server side controls the credential lifecycle

→ See Connect environments with other credentials

Next Steps​

After the environment is bound to the Agent, you can start managing resources within the environment:

→ Manage environment resources