ZoophostDocs

Connect an AI agent (MCP)

Run the Zoophost MCP server and let Claude, Cursor, Codex or any MCP-capable agent deploy and operate your workspace.

API & agents3 min read

Zoophost ships a Model Context Protocol (MCP) server. It exposes the platform as a set of tools an AI agent can call — deploy a site, follow a build, add a DNS record, create a mailbox, roll back a deploy.

The server is a thin client of the REST API. Authorization, auditing and the approval queue all live on the platform, so an agent gets exactly the access its API key has and nothing more.

1. Create a key for the agent

Console → Settings → API keys → New key.

For a deployment agent, a sensible start:

  • Role cap: developer
  • Scopes: site:read, site:deploy, site:write, deployment:read
  • Auto-approve: off
  • Monthly spend cap: set one if you include any billing scope

Copy the token — it is shown once.

2. Run the server

git clone <the zoophost-platform repo>
cd apps/mcp
npm install

export ZP_API_KEY=zp_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy
export ZP_API_URL=https://api.falcon.zoophost.com/api/v1
npm start

npm start speaks MCP over stdio, which is what desktop agents expect. To run it for a hosted agent instead:

ZP_TRANSPORT=http ZP_PORT=8848 npm start
# POST JSON-RPC to http://<host>:8848/mcp

Verify the wiring without changing anything:

npm run selftest

It checks the token, confirms the API is reachable, verifies every scope the tools rely on still exists, and reports the pending-approval count.

3. Register it with your agent

Most MCP hosts take a JSON block like this:

{
  "mcpServers": {
    "zoophost": {
      "command": "node",
      "args": ["/absolute/path/to/apps/mcp/src/index.js"],
      "env": {
        "ZP_API_KEY": "zp_live_…",
        "ZP_API_URL": "https://api.falcon.zoophost.com/api/v1"
      }
    }
  }
}

Restart the agent and the tools appear.

What the agent can do

Group Tools
Meta whoami, get_capabilities, list_pending_approvals, request_approval_status, list_recent_activity, api_request
Sites list_sites, get_site, provision_site, deploy_site, restart_site, start_site, stop_site, delete_site, get_site_envs, set_site_envs, tail_site_logs, get_plan_balance
Databases list_databases, create_database, get_database, delete_database, get_database_logs
Deployments list_deployments, get_deploy_status, cancel_deployment
DNS list_dns_zones, get_dns_zone, create_dns_zone, add_dns_record, update_dns_record, delete_dns_record, delete_dns_zone
Mail list_mail, list_mailboxes, create_mailbox, reset_mailbox_password
Storage list_storage, create_bucket, list_objects, presign_upload, presign_download, delete_objects
Billing get_wallet_balance, list_invoices, list_subscriptions, list_services

Billing is read-only in the MCP server on purpose. Purchasing is a human decision the agent cannot make on your behalf.

How approvals appear to the agent

A destructive tool on a key without auto-approve does not fail. It returns:

{
  "status": "pending_approval",
  "approvalId": "68f…",
  "nextStep": "Tell the user this action needs their approval, then poll …"
}

Nothing has changed. The agent should tell you which action is blocked and poll request_approval_status while you decide in Console → Settings → Agent approvals. Retrying the call would only queue a duplicate request.

Locking an agent down

Two environment variables narrow what the server exposes:

# Only these tools exist — the agent cannot even see the rest.
ZP_TOOLS=list_sites,get_site,get_deploy_status,tail_site_logs npm start

# Or: every mutating tool is removed.
ZP_READ_ONLY=true npm start

This is defence in depth, not the primary control. The API enforces the same limits independently through scopes, so a misconfigured client cannot exceed what the key allows.

Troubleshooting

Tools do not appear. Check the agent's MCP log. A missing ZP_API_KEY, or node not being on the host's PATH, are the usual causes.

Everything returns 401. The key is revoked, expired, or was copied with a line break. Mint a fresh one.

A call returns 403 with a scope name. That key does not have that scope. Add it to a new key — scopes are fixed at creation.

NO_WEBSITE_SLOTS. The workspace has no free Cloud Hosting slot. Order a plan or remove a site; the API will not over-allocate.

SPEND_CAP_EXCEEDED. The key has hit its monthly ceiling. Raise it in Console → Settings → API keys.

  • mcp
  • model context protocol
  • ai agent
  • claude
  • cursor
  • codex
  • automation
  • llm

Ready to use this

Everything the API provisions is a catalog plan you can see priced first.

  • Same catalog the console reads
  • INR pricing, GST included
See the plans behind the API
Still stuck? Open a ticket from Support tickets in the console, or email [email protected]. Include the service name, the exact error and what you already tried.