# Staticbot MCP server

Give Codex, Claude, Cursor, and other MCP-compatible agents safe access to [Staticbot](https://www.staticbot.dev). 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:

```text
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](https://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:

```bash
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:

```text
/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:

```json
{
  "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](CAPABILITY-PARITY.md) for the remaining dashboard/API differences.

### Platform updates and pending actions

`list_pending_actions` and `list_platform_updates` expose the same post-migration fixes as the project's
Sync tab. `check_platform_updates` refreshes the evidence and may enqueue approved automatic fixes;
it is a mutating operation. `apply_platform_updates` applies the selected fixes only after the user
approves the returned effects. Customer-owned branches get pull requests, never direct pushes.
`dismiss_platform_update` declines optional fixes; required fixes cannot be dismissed.
`refresh_platform_update` re-runs the read-only refresh of an update marked `canRefresh` (Refresh account
connections); it installs nothing and changes no credentials or user connections. Follow the
returned sync run and PR links. The server feature flag may keep these operations disabled during rollout.

### Backend controls and source updates

`get_backend_workflows` inspects the shared backend for exactly one connected project or migration.
Present every affected stage and the observed flags before using `operate_backend_workflows`.
These controls manage Staticbot's migrated Base44 scheduler on Supabase Cloud; unknown outcomes
remain unknown and are never retried automatically.

For tracked feature branches, inspect `list_connected_project_previews` and
`get_feature_branch_preview_settings`. A build requires the exact commit and build hint, including
any preview removed by the plan limit. Automatic settings keep the existing hosting-plan limits.
`trigger_sync` optionally redeploys all functions only after explicit confirmation; normal sync
requests stay compatible.

`preview_migration_source_update` resolves a chosen template version to its exact commit without
applying it. `update_migration_source` requires approval of that exact pair and prepares a new plan
for separate review; it does not approve target writes.

For a frontend hosted elsewhere, inspect `get_external_auth_domain` before approving its exact
backend and new public origin through `set_external_auth_domain`. This changes authentication
configuration, not frontend hosting or DNS. Even an UPDATED result needs real sign-in, reset and
magic-link testing.

### Cutover status and late source changes

`get_connected_project_cutover` reads retained Switch-tab evidence without starting a check.
`check_connected_project_cutover` scans the live app and checks the old backend for late writes;
it never copies data. Unknown, blocked or truncated checks remain qualified.

For Base44 catch-up, present the source, target, copy window and copy mode before using
`copy_connected_project_late_changes`. `INSERT_ONLY` leaves differing target records for review;
`FULL_UPDATE` overwrites them. Both require `confirmed=true` and the exact inspected `stateVersion`
as `expectedState`. A 409 requires new inspection and approval. Follow the returned sync run;
never retry an unknown outcome automatically.

`mark_cutover_conflicts_reviewed` requires a separate, explicit user decision about that copy's
conflicts. It advances Staticbot's watch window and does not repair database records. Partial
conflict lists require review of the remaining results in the dashboard. These additions need
the corresponding backend and hosted MCP release before clients can use them.

## 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.
- Platform updates are applied only after the user has seen each update's `whatApplyingDoes` and
  approved it; a required update is not approval. Customer branches get pull requests, never pushes.
- 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.

Use `get_migration_overview` for lightweight status polling. It returns phase/job counts, saved-report metadata, jobs needing attention and preview status, with `version` and `pollAfterMs`. It never loads raw payloads or changes the migration. Use `get_migration`, `get_migration_jobs`, discovery reports and job history for all existing technical details and before routing an action.

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.

`get_app_secrets` lists the app's secrets and per-user account connections (Google, Dropbox) by name
and state, never a value. `test_connection_credentials` asks the provider whether it recognises the
OAuth client the user saved for one connection, the dashboard's "Test credentials". It takes and returns
no credential value; the user enters values only in the dashboard at the returned `browserUrl`.

## Staticbot skills

The repository includes focused deployment, migration, and Continuous Sync skills plus a [general Staticbot Skill](https://github.com/bitfiction/staticbot-mcp/tree/main/skills/staticbot) 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](https://www.staticbot.dev)
- [Interactive API reference and API keys](https://app.staticbot.dev/developer)
- [npm package](https://www.npmjs.com/package/@staticbot/mcp)
- [Contributing and local verification](https://github.com/bitfiction/staticbot-mcp/blob/main/CONTRIBUTING.md)

## License

MIT