Connect CloudBase MCP to Claude Code — Control CloudBase Resources with Natural Language

In one sentence: claude mcp add cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest gives Claude Code 36 CloudBase tools (create collections / write cloud functions / deploy static hosting / cloud run / cloud storage / search) so you can go from a single prompt to a live CloudBase application without ever leaving the terminal.

Estimated time: 15 minutes | Difficulty: Beginner

Applicable Scenarios

• Using Claude Code as an AI assistant for a CloudBase project, letting it create databases, write functions, and deploy — without switching to the Console
• Team vibe coding: running the full cycle from requirement breakdown to production deployment through Claude Code
• Already using Claude Code's /spec / /no_spec workflow and want to layer in CloudBase domain knowledge so AI-generated code lands directly in production

Not Applicable

• Claude Code is not a production CI/CD tool — production deployments should still go through git push + pipeline. This recipe is intended for rapid iteration during development
• Cursor / Windsurf / CodeBuddy and other IDEs each have their own MCP integration path (different config files); this recipe covers only Claude Code (the claude mcp add command)
• Pure local tool MCP servers (file system access, process listing) are unrelated to CloudBase and run via stdio transport locally

Prerequisites

Dependency	Version
Claude Code	Latest (npm i -g @anthropic-ai/claude-code or claude.ai/code)
@cloudbase/cloudbase-mcp	@latest tag always fetches the newest published version (2.19.5 at the time of writing)
Node.js	≥ 18.15.0 (per cloudbase-mcp repo README)
CloudBase environment	Provisioned; note your envId
Tencent Cloud API keys	SecretId / SecretKey — generate from Tencent Cloud Console → API Keys

Step 1: Add cloudbase-mcp to Claude Code

Minimal command:

claude mcp add cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest

This command:

• Registers an MCP server named cloudbase
• Uses stdio transport (launches a local npx subprocess)
• @latest tag automatically resolves to the repo's most recent release

Inject credentials (so Claude doesn't ask for your env ID / keys on every conversation):

claude mcp add -e CLOUDBASE_ENV_ID=<your-env-id> \
  -e TENCENTCLOUD_SECRETID=<your-secret-id> \
  -e TENCENTCLOUD_SECRETKEY=<your-secret-key> \
  cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest

Run claude mcp list to verify:

cloudbase: npx -y @cloudbase/cloudbase-mcp@latest - ✓ Connected

✓ Connected means success. If you see ✗ failed to connect, see the Common Errors section below.

Step 2: Optional — Install the cloudbase-skills Package

cloudbase-mcp gives Claude capabilities (36 tool calls). Installing cloudbase-skills additionally gives it knowledge (CloudBase-domain prompt templates and coding plans):

npx skills add tencentcloudbase/cloudbase-skills

After installation, Claude Code gains:

• /spec — full workflow: requirements → design → task breakdown → implementation; ideal for new projects from scratch
• /no_spec — jump straight to code, skipping breakdown; ideal for bug fixes or adding a single feature
• Built-in coding plan skill — automatically executes code in planned steps before writing (enabled by default)

cloudbase-mcp works without this package — Claude will just rely entirely on its own reasoning when choosing tools and determining call order. With cloudbase-skills installed, it follows the CloudBase-recommended path.

Step 3: Overview of the 36 CloudBase MCP Tools

Once installed, Claude Code auto-discovers these tools (run /tools for the full list).

The design philosophy of CloudBase MCP is two-dimensional partitioning by domain × read/write: most domains come as a query* (read) + manage* (write) pair, so the 36 tools really map to ~18 conceptual pairs:

Category	Tool count	Main tools
Auth + Environment	3	auth login, envQuery environment/quota lookup, envDomainManagement security domain
Database (NoSQL / MySQL / Data Model)	8	NoSQL ×4: readNoSqlDatabaseStructure / writeNoSqlDatabaseStructure (collections + indexes), readNoSqlDatabaseContent / writeNoSqlDatabaseContent (data CRUD); MySQL ×2: querySqlDatabase / manageSqlDatabase; Data Model ×2: manageDataModel / modifyDataModel
Cloud Functions	2	queryFunctions list/details/logs/triggers, manageFunctions create/update/invoke/delete + manage triggers
Deployment (Hosting + Cloud Run + Storage + Gateway)	8	queryHosting / manageHosting, queryCloudRun / manageCloudRun, queryStorage / manageStorage, queryGateway / manageGateway
Application control (App Auth + Permissions + Apps + AI Agent)	8	queryAppAuth / manageAppAuth, queryPermissions / managePermissions, queryApps / manageApps, queryAgents / manageAgents
Utilities (Search + Templates + Logs + Cloud API + Incentive)	7	searchWeb, searchKnowledgeBase, downloadTemplate, downloadRemoteFile, queryLogs, callCloudApi, activateInviteCode

Full spec: cloudbase-mcp tools documentation.

Step 4: Hands-On — "Build Me a Todo App"

Open Claude Code and type:

Build me a todo app. Store data in CloudBase database,
use React + Vite for the frontend, and deploy to CloudBase Static Hosting.

(Optional: type /spec first to have Claude Code break the plan into steps before starting)

Claude Code automatically calls a series of tools. The log will look roughly like this:

✓ writeNoSqlDatabaseStructure   # creates `todos` collection + `createdAt` index
✓ Scaffold React + Vite project locally (npm create vite@latest todos-app)
✓ Write src/api.ts calling CloudBase Web SDK — init + signIn (uses envId automatically)
✓ Write src/App.tsx with list, input field, and delete button
✓ npm install
✓ npm run build
✓ manageHosting                  # uploads ./dist to /todos
✓ Returns hosting URL: https://<envId>-xxx.tcloudbaseapp.com/todos

The whole process takes 5–15 minutes. At decision points (e.g. "Add anonymous login?", "Paginate the list?") Claude will pause and ask you — answer and it continues.

Step 5: Verification

1. claude mcp list shows cloudbase: ✓ Connected
2. In Claude Code, run /tools and confirm you see 36 cloudbase.xxx tools in the list
3. After Step 4 deployment, open the returned hosting URL in a browser and confirm the todo app loads
4. CloudBase Console → Database → verify the todos collection exists with a few records Claude wrote during testing
5. Console → Overview → API call count should show a spike of several dozen calls (each tool call counts as one)

Common Errors

Error / Symptom	Cause	Fix
claude mcp list shows cloudbase ✗ failed to connect	Credentials not injected, or local npm registry cannot fetch the package	First run npx -y @cloudbase/cloudbase-mcp@latest --version to verify the package can be pulled. If that works, run claude mcp remove cloudbase then re-add with the -e flags
Tool call returns getCredential failed / signature mismatch	SecretId / SecretKey is wrong or lacks permissions	Regenerate a key pair at API Keys. In production, use a sub-account key with a CAM policy scoped to the current environment
environment not found / env id invalid	CLOUDBASE_ENV_ID is misspelled or the environment was deleted	Console → Overview, copy the current environment's envId (not the alias). Then run claude mcp remove cloudbase + claude mcp add -e CLOUDBASE_ENV_ID=...
Tool returns quota exceeded / rate limit	API call quota for the current plan has been reached	Console → Billing → check remaining API call quota. The free tier has call limits; upgrade your plan or wait for the monthly reset
Claude repeatedly generates signInAnonymously() code	Stale prompt template	After installing cloudbase-skills from Step 2, Claude follows the current recommended pattern using @cloudbase/node-sdk server-side credentials. See add-ai-nextjs for details

Full error code reference: https://docs.cloudbase.net/error-code/.

Billing Notes

• The @cloudbase/cloudbase-mcp package itself is free; installing and calling the MCP incurs no charge
• What is billed is the underlying CloudBase resource usage triggered by tool calls (database reads/writes, cloud function invocations, static hosting traffic) — standard CloudBase pricing applies
• Claude Code itself is billed by Anthropic subscription (Sonnet / Opus) and is unrelated to CloudBase
• Add .claude/ to .gitignore to prevent credentials injected by claude mcp add -e from being committed. In production, store credentials in your company's secrets manager rather than on a personal machine's main-account CAM key

Related Documentation

• connect-ai-mcp-server-cloud-run — package your own business capabilities as an MCP server and deploy to Cloud Run (the inverse of this recipe: here Claude Code is the client calling the official CloudBase MCP)
• add-ai-nextjs — after Claude Code finishes building your app with cloudbase-mcp, add AI chat capability to it
• CloudBase AI Toolkit — integration paths for Cursor / Windsurf / CodeBuddy and other IDEs
• cloudbase-mcp full tool spec — parameters and return values for all 36 tools