Connect AI agents (MCP)

The Zeloxa MCP server lets AI agents — Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, ChatGPT and any other client that speaks the Model Context Protocol — work with your Zeloxa Host sites. An agent can list your sites, check whether a deployment worked, read its build log, roll back, promote a deployment, connect a custom domain and publish a small static site.

• Server URL: https://mcp.zeloxalabs.com/mcp
• Transport: Streamable HTTP
• Sign-in: browser sign-in (OAuth), or an API token sent as Authorization: Bearer zx_…
• Setup page in the dashboard: Hosting → Connect AI agents (https://zeloxalabs.com/dashboard/host/agents)

The tools call the same operations as the Host API and the CLI, with the same scopes and the same error codes.

Choose how the agent signs in #

Token scopes are nested; higher ones include the lower ones:

Give an agent the narrowest scope that does the job: host:read for an agent that answers "is my site up?", host:deploy for one that may roll back.

API tokens are shown once, when you create them. None of the snippets below contain a real token; replace zx_YOUR_TOKEN with yours, and keep it out of any file you commit.

Set up your client #

Client configuration formats change from time to time. The snippets below were checked against each client's documentation in October 2026; the dashboard's Connect AI agents page always has the current versions.

Cursor #

Global: ~/.cursor/mcp.json. One project: .cursor/mcp.json.

Browser sign-in — Cursor opens the Zeloxa sign-in page when it first connects:

{
  "mcpServers": {
    "zeloxa": {
      "url": "https://mcp.zeloxalabs.com/mcp"
    }
  }
}

API token:

{
  "mcpServers": {
    "zeloxa": {
      "url": "https://mcp.zeloxalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer zx_YOUR_TOKEN"
      }
    }
  }
}

In a project's .cursor/mcp.json, read the token from an environment variable instead: "Authorization": "Bearer ${env:ZELOXA_TOKEN}".

Claude Code #

Browser sign-in, available in every project:

claude mcp add --transport http --scope user zeloxa https://mcp.zeloxalabs.com/mcp

Then run /mcp inside Claude Code, choose zeloxa and sign in.

API token:

claude mcp add --transport http zeloxa https://mcp.zeloxalabs.com/mcp \
  --header "Authorization: Bearer zx_YOUR_TOKEN"

For a team or CI, commit .mcp.json at the repository root and give each person or job its own token in ZELOXA_TOKEN:

{
  "mcpServers": {
    "zeloxa": {
      "type": "http",
      "url": "https://mcp.zeloxalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ZELOXA_TOKEN}"
      }
    }
  }
}

Claude Desktop and claude.ai #

Custom connectors are set up in the Claude app, not in a config file, and work the same in Claude Desktop and on claude.ai.

1. Open Customize → Connectors, choose + Add, then Add custom connector.
2. Name it Zeloxa and paste https://mcp.zeloxalabs.com/mcp.
3. Keep the default sign-in settings and add it.
4. Choose Connect and sign in with your Zeloxa account.

Team and Enterprise plans: an owner adds the connector under Organization settings → Connectors; members then connect it from Customize → Connectors.

With an API token instead: choose No sign in and, under Request headers, add Authorization: Bearer zx_YOUR_TOKEN.

Claude reaches remote servers from Anthropic's cloud, not from your computer; mcp.zeloxalabs.com is public, so nothing extra is needed.

VS Code #

.vscode/mcp.json in your project (or your user-level MCP configuration).

Browser sign-in — VS Code opens a browser window to sign in the first time:

{
  "servers": {
    "zeloxa": {
      "type": "http",
      "url": "https://mcp.zeloxalabs.com/mcp"
    }
  }
}

API token, prompted for once and kept in VS Code's secret storage rather than in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "zeloxa-token",
      "description": "Zeloxa API token",
      "password": true
    }
  ],
  "servers": {
    "zeloxa": {
      "type": "http",
      "url": "https://mcp.zeloxalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:zeloxa-token}"
      }
    }
  }
}

Windsurf (Devin Desktop) #

~/.codeium/windsurf/mcp_config.json. Open it from Cascade's MCP settings — Devin Desktop, Windsurf's new name, may keep it in ~/.config/devin/mcp_config.json. Windsurf uses serverUrl, not url.

{
  "mcpServers": {
    "zeloxa": {
      "serverUrl": "https://mcp.zeloxalabs.com/mcp"
    }
  }
}

API token: add "headers": { "Authorization": "Bearer zx_YOUR_TOKEN" } next to serverUrl, or "Bearer ${env:ZELOXA_TOKEN}" to read it from the environment.

ChatGPT #

Developer mode, on the web, for Plus, Pro, Business, Enterprise and Education accounts. ChatGPT connects with OAuth only — use browser sign-in.

1. Open Settings → Security and login and turn on Developer mode.
2. Open Plugins and choose + to create an app for a remote MCP server. Name it Zeloxa, use https://mcp.zeloxalabs.com/mcp and choose OAuth.
3. Sign in with your Zeloxa account when ChatGPT redirects you.
4. In a chat, choose Developer mode from the + menu and select Zeloxa.

ChatGPT asks before running a tool that changes something (rollback, promote, add domain, deploy). Business and Enterprise admins can publish the app to their workspace. After Zeloxa adds tools, refresh the app in its settings to pick them up.

Any other client #

Point it at https://mcp.zeloxalabs.com/mcp (Streamable HTTP). Clients that support MCP authorization discover the sign-in flow automatically; others can send Authorization: Bearer zx_….

Tools #

Every Hosting tool takes site as the site's slug (acme-site), its id, or its URL (https://acme-site.zeloxa.app). Deployments are named by their number for that site (12 or "#12") or their id.

Tools that change what is live are marked as such to the client (MCP tool annotations), so clients that confirm before acting will ask you first.

The same server also has Cloud tools (whoami, get_usage, list_ai_models, list_playground_models, ai_generate, storage_list, storage_put, storage_delete), metered against your Cloud plan. whoami shows which account and Hosting scopes the connection has.

For a real build — a framework project, anything over a few megabytes — use the CLI (zeloxa deploy) rather than host_deploy_files.

Example prompts #

• "List my Zeloxa sites and tell me which ones have a failed latest deployment."
• "Is acme-site up? Check the status of its latest deployment."
• "Why did the last deploy of acme-site fail? Read the build logs and suggest a fix."
• "Roll back acme-site to the previous deployment."
• "Promote deployment #12 of acme-site."
• "Add www.acme.com to acme-site and tell me exactly which DNS records to create."
• "Check whether www.acme.com is verified yet."
• "Build a one-page landing page for my bakery and deploy it to acme-site."

Errors #

A tool that fails returns an MCP tool error (isError: true) whose text is:

{
  "error": {
    "code": "DEPLOYMENT_NOT_READY",
    "message": "Deployment #7 is building.",
    "details": { "…": "…" },
    "hint": "Only deployments with status ready can go live. Check host_list_deployments and pick a ready one."
  }
}

code is stable; message and hint are written for the agent and may be reworded. Arguments that do not match a tool's input schema at all (a missing site, limit: 0) are rejected by the MCP layer before the tool runs, with an Input validation error: … message instead of this shape. The codes are the Host API's plus three from the MCP server itself:

Security #

• Your credentials stay in the MCP server. When you use a token, the server keeps only a hash of it plus its id, name and scopes; it re-checks the token on every request, so a revoked or expired token stops working immediately. The token itself is never passed on to the Hosting platform.
• Check the sign-in page. It names where access goes once you sign in (claude.ai, chatgpt.com, or an app on this computer). Browser sign-in gives full Hosting access, so if a link you did not start asks you to sign in, or the page names a site you do not recognise, close it.
• Scopes are checked twice: by the MCP server before it does anything, and again by the Hosting platform.
• Agents act on one account: the one you signed in to, or the one the token belongs to. Every query is limited to that account's sites.
• Some settings are dashboard-only. No agent, token or scope can create or revoke tokens, change integrations or webhooks, set site passwords or change security headers. A leaked token cannot lock you out or mint more tokens.
• Changes are recorded. Deployments (including ones published with host_deploy_files), rollbacks, promotions and domain changes made through MCP appear in Hosting → Activity, labelled with the account email or the token's name and prefix (token CI deploy (zx_AbC1234...)).
• Suspended accounts lose automation. If an account is canceled or past due, tokens and MCP connections stop working; the dashboard keeps working so billing can be fixed.
• Confirmation. Rollback, promote, deploy and add-domain are marked as changing your site, so ChatGPT, Claude and other clients that confirm write actions ask you first. Keep that on for production sites.

Troubleshooting #

The client says it needs authentication, or sign-in never finishes. Remove the server from the client and add it again, then sign in. In Claude Code, run /mcp and authenticate. The sign-in page needs an active Zeloxa account with an organization.

401 Invalid or revoked Zeloxa API key. The token is wrong, revoked or expired, or the account is suspended. Create a new one under Hosting → API tokens. Check the header is exactly Authorization: Bearer zx_… with no quotes or line breaks in the token.

INSUFFICIENT_SCOPE. The token does not have the scope the tool needs (see Tools). Create a token with that scope, or use browser sign-in.

SITE_NOT_FOUND. Ask the agent to run host_list_sites first. A slug is the subdomain part of the site URL (acme-site in acme-site.zeloxa.app).

host_rollback went back further than expected. Without to, every call goes back one more release. Use host_promote with the deployment you want live; deployments are never deleted by a rollback.

host_deploy_files says index.html is missing. The site needs index.html at its top level (or inside one shared folder such as dist/, which is removed).

New tools do not show up. Clients cache the tool list. Reconnect the server (ChatGPT: refresh the app in its settings).

PLATFORM_NOT_CONFIGURED, or UPSTREAM_ERROR on every call. A problem on Zeloxa's side; Cloud tools keep working. Contact support.