Connection Modes: Local vs Hosted

CloudBase MCP supports two connection modes:

• Local Mode: The MCP server runs locally on your machine via npx
• Hosted Mode: The MCP server runs on Tencent Cloud, and your IDE connects over HTTP

Choose the one that fits your needs.

---

Local Mode (Recommended)

What it means / when to use it

• Meaning: The MCP server runs on your machine via npx, alongside your IDE.
• Pros: Full feature set, including capabilities that rely on local filesystem access.
• Requirements: Node.js installed and npx available.

Configuration example

Add this to your IDE's MCP configuration (e.g. Cursor / WindSurf):

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {}
    }
  }
}

Optional environment variables (Local Mode)

In Local Mode, you can control behavior via environment variables. All of the following are optional.

Env var	Description	Default / Notes
CLOUDBASE_API_KEY	CloudBase environment-level API Key (recommended for CI/CD, MCP Server)	Use with CLOUDBASE_ENV_ID; takes priority over TENCENTCLOUD_* credentials; create in console
CLOUDBASE_ENV_ID	CloudBase environment ID (optional)	If not set, the first call will guide you through login and environment selection
CLOUDBASE_API_ENDPOINT	Custom endpoint for API Key credential exchange (advanced)	If not set, uses default https://<envId>.<region>.tcb-api.tencentcloudapi.com
TENCENTCLOUD_SECRETID	Tencent Cloud SecretId (optional)	If not set, it will be obtained via the login flow; see CAM API keys
TENCENTCLOUD_SECRETKEY	Tencent Cloud SecretKey (optional)	Same as above
TENCENTCLOUD_SESSIONTOKEN	Tencent Cloud temporary token (optional)	Only needed for temporary credentials; see STS
TCB_REGION	Tencent Cloud region, e.g. ap-shanghai (optional)	Uses SDK default if not set
TCB_AUTH_OAUTH_ENDPOINT	Custom device-code OAuth endpoint (advanced)	If not set, uses default
TCB_AUTH_CLIENT_ID	Custom device-code OAuth client_id (advanced)	If not set, uses default
TCB_AUTH_OAUTH_CUSTOM	Whether the custom endpoint uses a custom response format (advanced)	Defaults to false if endpoint is not set; defaults to true when endpoint is set
INTEGRATION_IDE	IDE identifier (e.g. Cursor, CodeBuddy) (optional)	Used for logging and capability adaptation
CLOUDBASE_MCP_PLUGINS_ENABLED	Enabled plugin list, comma-separated (optional)	Uses default plugin set if not set
CLOUDBASE_MCP_PLUGINS_DISABLED	Disabled plugin list, comma-separated (optional)	Similar to URL param disable_plugins
WORKSPACE_FOLDER_PATHS / PROJECT_ROOT	Project root path (templates, remote downloads, etc.) (optional)	Defaults to current working directory; in CI you can use GITHUB_WORKSPACE, etc.
CLOUDBASE_MCP_TELEMETRY_DISABLED	Set to true to disable telemetry (optional)	Telemetry enabled by default
CLOUDBASE_LOG_DIR	Log directory (optional)	Defaults to ~/.cloudbase-mcp/logs
CLOUDBASE_GUIDE_PROMPT	Set to false to disable some guide prompts (optional)	Some IDEs will show fewer hints

Credential priority

When multiple credentials are present, MCP selects in this order:

1. CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID (highest priority, recommended for platforms/CI)
2. TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY (permanent or temporary Tencent Cloud credentials)
3. Locally stored device-code login credentials (~/.config/.cloudbase/auth.json)

Which login env vars should I set?

In most cases, you don't need to configure these 3 variables: TCB_AUTH_OAUTH_ENDPOINT, TCB_AUTH_CLIENT_ID, TCB_AUTH_OAUTH_CUSTOM.

You only need to configure them if you're integrating with an enterprise/platform custom login middleware. See the official docs White-label mode without CAM sub-accounts.

• Personal dev / typical teams: use the default device-code login, no configuration needed

• Server, CI/CD, MCP Server, AI Agent: Recommended to use CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID (environment-level long-lived credentials, automatically exchange for temporary keys)

  {
    "CLOUDBASE_API_KEY": "<your-api-key>",
    "CLOUDBASE_ENV_ID": "<your-env-id>"
  }

  💡 API Keys can be created and managed in the CloudBase Console environment settings.

  ⚠️ API Keys have environment-level operation permissions. Please keep them secure and inject via environment variables instead of hardcoding them in config files.

• Traditional key method: set TENCENTCLOUD_SECRETID, TENCENTCLOUD_SECRETKEY (optionally TENCENTCLOUD_SESSIONTOKEN) + CLOUDBASE_ENV_ID

• Enterprise custom login middleware: Usually just configure TCB_AUTH_OAUTH_ENDPOINT first; see White-label mode

Minimal example:

TCB_AUTH_OAUTH_ENDPOINT=https://auth.your-domain.com/oauth

Notes:

• TCB_AUTH_CLIENT_ID: only set if your custom auth service requires a fixed client_id
• TCB_AUTH_OAUTH_CUSTOM: when using a custom TCB_AUTH_OAUTH_ENDPOINT, it should typically be true (now usually auto-handled)

Credential priority

When multiple credentials are present, MCP selects in this order:

1. CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID — CloudBase environment-level API Key
2. TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY — Tencent Cloud permanent/temporary credentials
3. Locally stored device-code login credentials (~/.config/.cloudbase/auth.json)

---

Hosted Mode

What it means / when to use it

• Meaning: MCP runs on Tencent Cloud, and your IDE connects over HTTP—no need to install or run Node locally.
• Pros: No local environment dependency; it works once you provide credentials.
• Limitations: Some capabilities that require local filesystem access are unavailable (e.g. uploading local files, downloading templates into your workspace).

Configuration example

Replace <env_id>, <Tencent Cloud SecretId>, <Tencent Cloud SecretKey> with your environment ID and Tencent Cloud API keys:

{
  "mcpServers": {
    "cloudbase": {
      "type": "http",
      "url": "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=<env_id>",
      "headers": {
        "X-TencentCloud-SecretId": "<Tencent Cloud SecretId>",
        "X-TencentCloud-SecretKey": "<Tencent Cloud SecretKey>"
      }
    }
  }
}

• Environment ID: See it in the CloudBase Console.
• SecretId / SecretKey: Create/view them in Tencent Cloud CAM API keys.

Control plugin scope via URL (Hosted Mode only)

In the url, you can control the plugin scope via query parameters:

• enable_plugins: only enable specified plugins, multiple plugins use comma separation, e.g. only enable env and database
• disable_plugins: disable specified plugins from the default plugin set, multiple plugins use comma separation, e.g. disable rag and env

# Only enable specified plugins
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&enable_plugins=env,database

# Disable specified plugins
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&disable_plugins=rag,env

The currently configurable plugin names are subject to mcp/src/server.ts; it is recommended to prioritize canonical names: env, database, functions, hosting, storage, setup, rag, download, gateway, cloudrun, app-auth, permissions, logs, agents, invite-code, capi, apps.

Environment variables (Hosted Mode)

In Hosted Mode, MCP runs in the cloud, so environment variables are configured server-side. If you host your own MCP service, you can refer to MCP Tools – Hosted MCP Configuration for the optional env var table (e.g. TENCENTCLOUD_SECRETID, TENCENTCLOUD_SECRETKEY, CLOUDBASE_ENV_ID, etc.).

If you use Tencent Cloud's hosted MCP, you can pass env_id and credentials via the URL and headers as shown above—no server-side env vars needed.

---

Self-hosted Server Deployment (Cloud Mode)

What it means / when to use it

• Meaning: Run the MCP server on your own server. Enable Cloud Mode via environment variables to expose a Streamable HTTP interface.
• Advantages: Fully self-managed deployment, integrable with existing infrastructure.
• Security: When Cloud Mode is enabled, tools that involve local filesystem reads/writes and local process launches are disabled one by one (see the complete list below), preventing remote callers from accessing the server's local resources.

How to enable

Enable Cloud Mode via any of the following (pick one):

# Method 1: Environment variable
export CLOUDBASE_MCP_CLOUD_MODE=true

# Method 2: Alternative environment variable
export MCP_CLOUD_MODE=true

# Method 3: CLI argument
npx @cloudbase/cloudbase-mcp@latest --cloud-mode

Tools disabled in Cloud Mode

When Cloud Mode is enabled, the following tools that involve local filesystem or local processes are automatically skipped during registration:

Tool	Reason for disabling
downloadRemoteFile	Downloads remote files to local filesystem
downloadTemplate	Downloads project templates to local
manageCloudRun	Involves local service startup (action="run")
manageStorage	Involves local file upload/download
manageApps	deployApp reads local filePath to upload code
createFunction	Involves local code upload
updateFunctionCode	Involves local code upload
setupEnvironmentId	Involves local configuration file operations

Security architecture

CloudBase MCP provides layered security for different deployment scenarios:

┌───────────────────────────────────────────────────────┐
│              Local Mode                               │
│  - All tools available                                │
│  - Caller = developer (already has full machine        │
│    control)                                           │
│  - Communication: stdio / localhost                    │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│              Cloud Mode                               │
│  - Local file/process tools automatically disabled    │
│  - Three-layer filtering: server-side registration    │
│    filtering + client-side whitelist (dual redundancy) │
│  - Remote callers cannot access server local resources │
│  - Communication: HTTPS (Streamable HTTP)              │
└───────────────────────────────────────────────────────┘

Important: In Local Mode, tools like downloadRemoteFile and manageCloudRun(action="run") are normal product features—equivalent to running curl or node app.js on your terminal. These tools only run on the developer's local machine and pose no privilege escalation risk. If you need to deploy the MCP service on a remote server and expose an interface externally, be sure to enable Cloud Mode.

Deployment mode selection guide

Scenario	Recommended Mode	Notes
Personal development	Local Mode (npx)	Full feature set, no extra configuration needed
Team collaboration / remote service	Tencent Cloud Hosted Mode	No ops overhead, security protection enabled automatically
Self-hosted server	Cloud Mode	Be sure to set CLOUDBASE_MCP_CLOUD_MODE=true

---

Supported Plugins

The current plugin names, default enabled set, and compatible aliases are subject to mcp/src/server.ts. The table below lists the currently supported canonical names:

Plugin	Default Enabled	Description
env	Yes	Environment login, environment queries, security domain management
database	Yes	NoSQL / SQL / data models
functions	Yes	Cloud function queries, creation, updates, invocation
hosting	Yes	Static hosting and domain management
storage	Yes	Cloud storage file management
setup	Yes	Project templates, IDE rules, and configuration downloads
rag	Yes	Knowledge base search and web search
download	Yes	Download remote files to local
gateway	Yes	Cloud function access entry and route management
cloudrun	Yes	CloudBase Run service initialization, deployment, and management
app-auth	Yes	App-side authentication configuration
permissions	Yes	Permissions, roles, and security rules
logs	Yes	Log service status and log search
agents	Yes	Agent queries and management
invite-code	Yes	AI coding incentive activation
capi	Yes	Generic Cloud API calls
apps	Yes	CloudApp application and version management

Note: permissions is compatible with old aliases security-rule, security-rules, access-control, secret-rule, secret-rules, users; app-auth is compatible with old alias auth-config. Please prioritize using canonical names for new documentation and new examples.

If not configured, plugins with "Default Enabled" = "Yes" in the table above are enabled by default; plugin scope can be controlled via environment variables or URL parameters. The multi-value format for enable_plugins / disable_plugins and CLOUDBASE_MCP_PLUGINS_ENABLED / CLOUDBASE_MCP_PLUGINS_DISABLED is comma-separated.

Supported Tools

The number and names of tools evolve with versions. For complete parameter reference, see MCP Tools; to confirm whether a tool or plugin actually exists, please prioritize the registration results in mcp/src/server.ts and mcp/src/tools/*.ts.