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; also reads CLOUDBASE_APIKEY for compatibility (aligned with @cloudbase/js-sdk / @cloudbase/node-sdk; the underscore form CLOUDBASE_API_KEY takes precedence); 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_SITE	Site: domestic (China site) or intl (International site) (optional)	If not set, inferred from region via a mapping table; ap-singapore is ambiguous and defaults to intl. Domestic-site Singapore users must explicitly set domestic to avoid being treated as International site
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
TCB_TCR_USERNAME	Personal-edition TCR push username, i.e. Tencent Cloud account UIN (optional)	Only needed for HTTP cloud function personal-edition image builds (imageType=personal with local / cloud); shares the same name as cloudbaserc's {{env.TCB_TCR_USERNAME}}—CLI and MCP use the same set of variables
TCB_TCR_PASSWORD	Personal-edition TCR fixed password (optional)	Same as above; once configured, credentials do not need to be passed in tool parameters, keeping passwords out of the AI context. Get personal-edition image registry password
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

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 doc Isolation 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)
• 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

Credential priority

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

1. CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID — CloudBase environment-level API Key (if CLOUDBASE_API_KEY is not set, falls back to reading CLOUDBASE_APIKEY)
2. TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY — Tencent Cloud permanent/temporary credentials
3. Locally stored Device Flow login credentials (~/.config/.cloudbase/auth.json)

Login modes and query scope

The two login approaches have different visible environment scopes—this is a credential permission boundary, not a lost environment:

Login method	auth(status) field	What you can see
Account-level (device / web / Tencent Cloud SecretId)	credential_scope=account	Environments the account has access to in the current region; other regions require explicit queries
Environment-level API Key (CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID)	credential_scope=single_env	Only the bound envId—cannot list other environments or other regions

Cross-region queries (account-level credentials only):

• MCP: queryEnv(action="list", region="ap-singapore") (envQuery is synonymous)
• MCP management plane: callCloudApi(service="tcb", action="DescribeEnvs", region="ap-singapore"). Do not put Region inside params (will cause The parameter Region is not recognized)
• CLI: tcb env list -r ap-singapore --json

Binding an environment in another region: under account-level login, auth(action="set_env", envId="<EnvId>") does not require the envId to appear in the current region's candidate list; environment-level API Key cannot rebind to a different envId.

API Key mode example

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "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.

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 defaults to true automatically when the endpoint is configured

---

Site and Region (site / region)

CloudBase has two separate account systems and login domains: the China site (domestic, cloud.tencent.com) and the International site (intl, tencentcloud.com). MCP uses site to determine the login domain / credential slot, and region to determine the API routing target—the two are decoupled.

Resolution priority

Explicit cloudBaseOptions.site/region
  > Environment variables TCB_SITE / TCB_REGION
  > Project-level config .cloudbase/project.json
  > cloudbaserc.json (field-level fallback; site is an MCP extension field)
  > Global default: domestic + ap-shanghai

Default relationship between region and site

region	Resolution when site is not configured
ap-shanghai / ap-guangzhou	domestic (China site)
ap-singapore	Ambiguous: both China site and International site have this region; defaults to intl when site is not configured (for backward compatibility)

International site users

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TCB_SITE": "intl",
        "TCB_REGION": "ap-singapore"
      }
    }
  }
}

China-site Singapore users (important migration guide)

The China site now supports the Singapore region. Setting only TCB_REGION=ap-singapore will default to International site behavior (login redirects to the International site, NoSQL tools are skipped). China-site Singapore users must explicitly configure the site:

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TCB_SITE": "domestic",
        "TCB_REGION": "ap-singapore"
      }
    }
  }
}

You can also use a project-level config .cloudbase/project.json (a standalone file, not merged into cloudbaserc.json) so that all sessions in the same directory automatically pick up the correct site:

{
  "site": "domestic",
  "region": "ap-singapore",
  "envId": "your-env-id"
}

The envId here serves as the default environment for the project. Resolution priority:

Explicit cloudBaseOptions.envId
  > Environment variable CLOUDBASE_ENV_ID
  > Currently bound environment in the process (auth(action="set_env") result)
  > Project-level config .cloudbase/project.json envId
  > cloudbaserc.json envId (field-level fallback)
  > Environment from account login state
  > Returns ENV_REQUIRED, guiding a call to auth(action="set_env")

cloudbaserc.json fallback notes (for existing CLI projects—no need to duplicate binding config):

• Field-level fallback: project.json and cloudbaserc.json complement each other field by field (e.g. if project.json only specifies site and cloudbaserc.json only specifies envId, both take effect); for the same field, project.json takes precedence
• envId / region support literal values and {{env.KEY}} templates: templates are resolved from the project root's .env / .env.local (same source as CLI); {{private.X}} and templates that fail to resolve are skipped and fall through to the next level without error
• MCP does not write cloudbaserc.json: it is a human-maintained deployment config managed by CLI (CLI also writes back to it automatically after deployment); machine-managed binding persistence uses .cloudbase/project.json

Because this file lives inside the repository and is committed with it, newly spawned MCP processes and every Git worktree of the same repository will automatically hit the same environment—no need to set_env again for each worktree; different repositories each read their own file, so bindings never cross-contaminate.

Multi-site credential coexistence

Login credentials are stored in separate slots by site (~/.config/.cloudbase/auth.json's credential has been upgraded to credential.domestic / credential.intl). China site and International site logins can coexist; switching environments does not require re-login. Legacy single-slot data is automatically treated as domestic when read and automatically upgraded to the slotted format on the first write-back.

---

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, pg_database, pg_storage, mysql_database, functions, hosting, storage, setup, rag, download, gateway, cloudrun, app-auth, permissions, logs, agents, apps, capi, database-nosql, database-sql, data-model.

Specify site via URL (Hosted Mode only)

Hosted Mode distinguishes between China site (domestic) and International site (intl) just like Local Mode. You can explicitly specify the site via the site query parameter for correct routing in scenarios like the ap-singapore region on the China site:

• site=domestic: China site (cloud.tencent.com)
• site=intl: International site (tencentcloud.com)
• If site is not passed, the server resolves it based on environment ownership; since both the China site and International site have the ap-singapore region, it defaults to intl when ownership cannot be determined

# China-site Singapore region: must explicitly pass site=domestic to avoid being treated as International site
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&site=domestic

China-site Singapore users (TCB_REGION corresponding to ap-singapore) should always include site=domestic in the hosted URL; otherwise login and NoSQL tools may be treated as International site.

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.); the site can also be specified via the TCB_SITE environment variable (domestic / intl), with behavior consistent with Local Mode.

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; to specify a site, add site=domestic or site=intl directly to the URL (see above).

---

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
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 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 database + data models (combined registration)
pg_database	Yes	PostgreSQL database
pg_storage	Yes	PostgreSQL storage
mysql_database	Yes	MySQL database
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, skills, OpenAPI and official documentation retrieval
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
apps	Yes	CloudApp application and version management
capi	Yes	Generic Cloud API calls
database-nosql	No	NoSQL database only (subset of database)
database-sql	No	SQL database only (subset of mysql_database)
data-model	No	Data models only (subset of database)

Compatible aliases (canonical names are recommended):

Alias	→ canonical
access-control	permissions
auth-config	app-auth
security-rule / security-rules	permissions
secret-rule / secret-rules	permissions
users	permissions
mysql / mysql-database	mysql_database
sql-database	mysql_database

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.