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.
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 |
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

