staticbot-mcp

Staticbot MCP server

Give Codex, Claude, Cursor, and other MCP-compatible agents safe access to Staticbot. The server exposes typed tools for deploying websites, migrating application backends, and operating continuous sync while Staticbot keeps credentials and long-running workflow state outside the model context.

Two ways to connect

Connect the hosted server — no install, no API key. Point an MCP client that supports remote servers with OAuth at:

https://mcp.staticbot.dev/mcp

You sign in to Staticbot, choose what to grant, and the client stores the connection. If you do not have a Staticbot account yet, one is created when you first connect.

Run it locally — for clients that launch MCP servers as a local process. Needs Node.js 20 or newer and a Staticbot API key from app.staticbot.dev/developer.

Both expose the same tools. The hosted server acts as the person who authorized it and never sees an API key; the local server uses the API key you give it.

Install as a Codex plugin

This repository is also a Codex plugin. Its manifest bundles the Staticbot MCP server with four intent-focused skills:

• deploy-web-app-with-staticbot deploys a repository without making the agent choose a cloud provider. Staticbot analyzes the repo, classifies the workload, and selects the supported AWS or Cloudflare target plus its customer-owned or Staticbot-managed ownership model.
• migrate-vibe-coded-app moves Base44, Lovable, Bolt, or Firebase backends to customer-owned Supabase infrastructure with discovery and approval gates.
• sync-vibe-coded-app keeps migrated projects synchronized while preserving destructive-change review.
• live-migrate-ai-built-app cuts a live Lovable or Base44 app over to the migrated stack during a planned maintenance window: test migration, cutover plan, maintenance page, source write freeze, fresh final copy, verification, and domain switch. The builder-specific freeze steps are in live-migrate-lovable-app and live-migrate-base44-app.

The general staticbot skill remains available as a direct REST API fallback.

Add the public GitHub marketplace, then install Staticbot:

codex plugin marketplace add bitfiction/staticbot-mcp
codex plugin add staticbot@staticbot

Restart the ChatGPT desktop app or Codex after adding the marketplace if Staticbot does not appear immediately. This preview plugin uses the local MCP transport, so set STATICBOT_API_KEY in the environment that launches the app. The hosted OAuth connection at https://mcp.staticbot.dev/mcp remains the lowest-friction option when you only need MCP tools rather than the bundled skills.

Install as a Claude Code plugin

Claude Code does not require Staticbot to be accepted into a central plugin registry. Add the self-hosted marketplace directly from this GitHub repository, then install the plugin:

/plugin marketplace add bitfiction/staticbot-mcp
/plugin install staticbot@staticbot

Set STATICBOT_API_KEY in the environment that launches Claude Code. The plugin starts the published @staticbot/mcp package with npx and inherits that environment; STATICBOT_API_URL remains optional for self-hosted or local Staticbot APIs.

The installed skills are namespaced by the plugin. For example, use /staticbot:deploy-web-app-with-staticbot, /staticbot:migrate-vibe-coded-app, /staticbot:sync-vibe-coded-app, or /staticbot:live-migrate-ai-built-app. Restart Claude Code or run /reload-plugins after installation if the plugin is not immediately available.

Configure your MCP client directly

Hosted (OAuth)

For clients that support remote MCP servers, add https://mcp.staticbot.dev/mcp and authorize when prompted. The client discovers where to sign in from the server itself; there is nothing to copy or paste, and no credential is stored on your machine.

Local (API key)

Add the published package to your project or global MCP configuration:

{
  "mcpServers": {
    "staticbot": {
      "command": "npx",
      "args": ["-y", "@staticbot/mcp"],
      "env": {
        "STATICBOT_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Hosted Staticbot at https://app.staticbot.dev is the default. Do not set STATICBOT_API_URL for the hosted service; override it only when using a self-hosted or local Staticbot API.

Keep the API key in your MCP client's secret or environment configuration. Do not paste it into chat or commit it to a repository.

What agents can do

The server groups its tools around user outcomes:

• Analyze a public website URL for its platform, backend and supported migration/hosting paths, without requiring connected integrations
• Inspect templates, stacks, deployments, and integration connections
• Resolve the repository to work on from a connected GitHub or GitLab account, private repositories included
• Create and monitor static-site and SSR deployments
• Inspect deployment DNS, safely push deployment-owned records to linked Cloudflare zones, and recheck custom-hostname verification
• Choose where a Cloudflare Workers app is hosted — Staticbot's account, or the user's own connected Cloudflare account — and check a hostname is deployable before creating anything
• Choose whether an AWS-hosted static site is deployed into Staticbot's managed account or the user's own connected AWS account
• Create a customer-owned Supabase project, wait until it is healthy, and use it as a migration target
• Migrate Lovable, Bolt, Firebase, and Base44 projects to Supabase targets
• Inspect migration discovery results and guide users through approval and choice gates
• Set a migration's live-app URL, read its scan and inspect retained live-commit comparisons
• Create previews and download portable migration packages
• Build connected-project previews, switch live deployment to the builder branch, or sync a migration preview onto live
• Inspect shared repository-webhook scope and explicitly set up, reset or disable GitHub push automation
• Trigger, review, retry, or skip continuous-sync runs
• Roll back or redeploy a website using valid pinned versions returned by Staticbot

The tool schemas and descriptions are the runtime contract seen by MCP clients. They contain the operational instructions an agent needs at the moment it selects a tool.

Website URL checks

scan_website starts or reuses an authenticated workspace check through POST /api/v1/site-scans. It needs a Staticbot account but no repository, database, or cloud integration. Poll the returned scan.id with get_website_scan (GET /api/v1/site-scans/{id}), waiting pollAfterMs between requests while the scan is queued or running. Terminal results include detection, support and hosting/migration estimates, or an explicit failure. A check never starts a deployment or migration.

This uses the existing workspace scanner with its quotas, cache, target throttle, bounded queue and public-address protections. The anonymous marketing-page API keeps its separate Turnstile flow. API/MCP results contain the customer summary rather than raw extracted scripts or contact history.

Connected-project operations

Read get_connected_project_operations before preview/live/webhook changes. It returns the current builder/live branches, effective role permissions and repository-webhook consumers. Mutation tools require explicit confirmation; live operations require those exact branch names and webhook actions require the returned repository configuration ID. A changed target returns 409 and needs fresh inspection and approval. Feature flags, workspace roles, persisted-link validation and agency-client restrictions remain enforced by the backend. Webhook reset/deletion uses the existing best-effort upstream removal, so a local configuration change is not proof that GitHub deleted the old hook.

The backend route must be deployed before enabling these tools in the hosted MCP server. See the capability audit for the remaining dashboard/API differences.

Example requests

• “Deploy this repository with Staticbot and tell me what DNS records I need.”
• “Push this deployment's required records to my linked Cloudflare zone, then recheck verification.”
• “Migrate my Base44 app to my Supabase project. Stop for approval before making changes.”
• “Show me what changed in the latest sync run and explain any destructive SQL.”
• “List valid rollback versions for this deployment, but do not roll back yet.”

Safety contract

Staticbot tools are designed around explicit human control:

• Discovery results are presented before a migration is confirmed.
• Choice gates are shown to the user instead of being silently defaulted.
• Destructive sync changes pause for review.
• Failed work is explained before an agent retries or skips it.
• Rollbacks use an exact version returned by list_rollback_versions and require confirmation.
• Long-running operations return durable state that can be resumed across agent sessions.
• The hosted server acts strictly as the person who authorized it, within the permissions they granted, and can reach nothing outside their own organization.

Migration tools are shared by the local API-key and hosted OAuth servers. Before routing any action, check executionCompatibility.locked: locked runs cannot resume or retry, even if their old status is IN_PROGRESS. Reports/history remain readable; start a new migration with fresh discovery and prefer a clean target after previous writes. Hosting and Continuous Sync have independent lifecycles.

For customer-owned native Supabase sources, explicitly select sourceIntegrationInstanceId independently of the target supabaseIntegrationInstanceId. One connection may own both projects, or each project may use a different connection; source and target projects must differ. Lovable Cloud has no source Management API connection and never borrows the target connection.

When a migration response contains pendingAction, the client should treat it as the source of truth for the next step. Clients should not hard-code Staticbot's internal pipeline phases.

Migration discovery can expose two additional reviewed actions. preFlightGate contains the exact export-versus-replay choices an agent must present before calling confirm_migration with the selected gateChoice. targetConflictReport lists objects already present on the target and offers database, Storage, or whole-project cleanup. clean_migration_target is irreversible and requires separate confirmation of both the exact scope and returned target project ref.

Before approval, inspect_migration_source can queue deeper inspection when the discovery report offers it. Committing and deploying the helper in the source account requires explicit authorization with authorizeHelperDeployment: true. Review the refreshed report before approving target writes. list_migration_discovery_revisions and get_migration_discovery_revision expose retained reports; execution revisions and job history preserve the evidence of past attempts.

get_migration_handoff_report returns Markdown with gaps, manual actions, remediation prompts, a names-only secret checklist, preview and current execution evidence. An optional discovery revision does not select historical execution. Migrated schedules remain staged inactive; the customer reviews and runs the report's guarded activation SQL at cutover when available. It preserves source-disabled jobs. Resolve staging errors before activation; reading a report never activates jobs.

Staticbot skills

The repository includes focused deployment, migration, and Continuous Sync skills plus a general Staticbot Skill for Codex or Claude environments that can operate the REST API directly without an MCP server. The direct-API workflow fetches the live OpenAPI contract and applies the same approval and credential-handling rules.

Use the MCP package when your client supports MCP. Use the Skill when direct API access from a command-line agent is more appropriate.

Environment variables

These apply to the local server. The hosted server needs none of them.

Variable	Required	Default	Purpose
STATICBOT_API_KEY	Yes	—	Authenticates requests to Staticbot
STATICBOT_API_URL	No	https://app.staticbot.dev	Override only for a self-hosted or local API

Documentation

• Staticbot website
• Interactive API reference and API keys
• npm package
• Contributing and local verification

License

MIT