@alpacacloud/mcp

@alpacacloud/mcp

Model Context Protocol (MCP) server for Alpaca Cloud.

Connect an AI agent (Claude, Cursor, Windsurf, etc.) to an Alpaca Cloud project — run SQL, manage schema, auth users, and storage, with no manual token plumbing.

Alpaca Cloud is an all-in-one platform: Postgres + Auth + Storage + Realtime + Edge Functions, plus static-site hosting and Docker app hosting — one platform, SDK, CLI, and MCP server.

Install / run

npx @alpacacloud/mcp@latest --project-url=https://<project>.alpaca-cloud.com --apikey=<service_role_key>

Claude Code (one line):

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

Or in a Claude Desktop / Cursor MCP config:

{
  "mcpServers": {
    "alpacacloud": {
      "command": "npx",
      "args": ["@alpacacloud/mcp", "--project-url=https://<project>.alpaca-cloud.com", "--apikey=<service_role_key>"]
    }
  }
}

Env vars also work (legacy ALPACABASE_* names still accepted as a fallback):

Var	Purpose
ALPACACLOUD_URL	Your project URL (project-scoped DB/Auth/Storage tools)
ALPACACLOUD_SERVICE_KEY	Project service_role key
ALPACACLOUD_ACCOUNT_TOKEN	Your personal access token (alp_pat_…) — unlocks the account-wide Sandboxes + Workflows tools. One token grants full account access; no separate sandbox permission.
ALPACACLOUD_API_URL	Account API base. Defaults to https://api.alpaca-cloud.com
ALPACACLOUD_SANDBOX_TEMPLATE	Default sandbox image (python/node/base). Defaults to python
ALPACACLOUD_SANDBOX_NETWORK	true to allow outbound network (pip/npm installs) in new sandboxes. Defaults to false

HTTP transport (--http) requires MCP_AUTH_TOKEN unless bound to localhost.

Self-describing for any AI

The server advertises tools, resources, and prompts so any MCP-capable AI discovers the whole platform on connect — no prior knowledge needed:

• Resources — readable markdown guides: alpacacloud://overview, …/database, …/auth, …/storage, …/realtime, …/edge-functions, …/frontend-hosting, …/app-hosting, …/branching, …/backups-pitr, …/sandboxes (beta), …/management-api. Read alpacacloud://overview first.
• Prompts — guided workflows: explore-project, build-backend, add-vector-search, setup-auth, deploy-site, deploy-docker-app.
• Tools — the 23 below, incl. platform_capabilities (machine-readable catalog).

Tools (23)

Discovery

• platform_capabilities — the full catalog of everything Alpaca Cloud can do, and which parts are managed here vs via the account Management API. Call this first.
• get_project_info — REST / auth / realtime endpoints + S3 details.

Database (Postgres 16)

• run_sql — any SQL via the service_role run_sql RPC (rows for SELECT, {ok} for DDL/DML)
• list_tables · get_table_schema · create_table · list_extensions (pgvector-ready)

Auth (per-project end users)

• list_auth_users · create_auth_user · delete_auth_user

Storage

• list_buckets · create_bucket · list_objects (upload/download/signed URLs via the SDK or the S3 API)

Sandboxes — code execution (E2B / Fly Machines style) · needs ALPACACLOUD_ACCOUNT_TOKEN

• run_code — one-off: spin up an ephemeral sandbox, run code, tear down
• create_sandbox · run_in_sandbox · list_sandboxes · delete_sandbox — persistent sandboxes (exec commands/code, files)

Workflows — automation (n8n style, 400+ nodes) · needs ALPACACLOUD_ACCOUNT_TOKEN

• list_workflows · create_workflow · run_workflow
• list_workflow_node_types (discover nodes before building) · list_workflow_templates

Project-scoped vs account-level

Two scopes:

• Project-scoped (service_role key): Database, Auth, Storage.
• Account-scoped (ALPACACLOUD_ACCOUNT_TOKEN = a personal access token from the dashboard → API Tokens): Sandboxes (code execution) and Workflows (automation). Set it via --account-token= or the ALPACACLOUD_ACCOUNT_TOKEN env var.

Other account-wide actions — create projects, deploy frontends/apps, scaling, templates, alerting, billing — are exposed through the Management API (OAuth2) at api.alpaca-cloud.com/mgmt/v1 or the dashboard. platform_capabilities lists all of it.

Security

The service_role key has full access and bypasses RLS — treat all results as privileged. Tool errors are returned as { "error": "…" } (not thrown). For the HTTP transport, always set MCP_AUTH_TOKEN and keep the bind localhost-only unless you intend otherwise.