Connect Agents - MetroPanel Docs

How to safely let Cursor, Claude Code, OpenAI Codex, and similar AI tools work with hosting account — what this is, how it works, what AI can (and cannot) do, and how to stay safe.

This is in Beta — for testing only, not production-ready. Do not rely on it for live customer workloads yet. Users still need the feature on their package or account.

What is this?

Connect agents lets you create a special agent token for your hosting account. You paste that token into an AI coding tool (Cursor, Claude Code, Codex, etc.). The tool can then call MetroPanel’s secure API — with the same kind of limits you already have in the panel — to inspect or manage your apps, domains, databases, and related account info.

MetroPanel does not run ChatGPT inside the panel for this feature. Your AI tool runs on your computer (or your IDE). MetroPanel only accepts carefully limited API requests when you give it a token.

This is different from:

Security → API Tokens (admins / resellers) — for billing systems like WHMCS
Your panel password — never put your login password into an AI tool

How it works

You (hosting user) → Create agent token in MetroPanel (Connect agents) → Copy token + IDE snippet → Paste into Cursor / Claude Code / Codex → AI tool talks to MetroPanel API → Only your account’s resources (policies + token permissions)

In short:

You mint a token in the panel (shown once).
Your IDE runs a small connector (MCP) that uses that token.
Every request is checked: valid token, allowed permission, and “is this your account?”
You can revoke the token anytime — the AI tool stops working immediately.

Setup

Sign in to MetroPanel as the hosting account user (not required to be server admin).
Open Connect Agents in the sidebar.
Choose a name (e.g. “Cursor laptop”), an access level, and expiry days.
Click Generate token.
Copy the token immediately — it will not be shown again.
Click Connect IDE… and pick the tab for your tool (Codex / Cursor / Claude / Advanced).
Paste the snippet into that tool’s MCP / config settings, then restart or reload the tool if needed.
Open Try these prompts on the same page, copy a prompt into your AI chat, edit placeholders, and send.

If you close the success message without copying the token, generate a new one and revoke the unused one.

Access levels

Preset	Best for	Allows
Read only	Safe default — explore, status, Q&A about your account	List/inspect apps, domains, databases, cron, usage
Manage my apps	When the AI should change things or put a site online	Everything in Read, plus install/remove apps, manage domains/DBs/cron, and ZIP / Git deploy to PHP · Node · Static apps (still only on your account)

Start with Read only. Switch to Manage only when you trust the tool and need it to perform changes.

Security notes

Treat the token like a password. Anyone with it can use the permissions you selected on your account.
Copy once, store safely. Do not paste tokens into public chats, GitHub issues, or screenshots.
Prefer Read only until you need Manage.
Use expiry (e.g. 30–90 days) and rotate tokens periodically.
Revoke unused tokens (old laptop, finished project, shared machine).
One token per device/tool makes revocation easier.
Never share your panel login password with an AI tool when a token exists for this purpose.
Agent tokens cannot escalate to server admin powers — but they can change your apps if you chose Manage.

If you suspect a leak: open Connect agents → Revoke that token immediately, then create a new one.

FAQ

Do I need different prompts for Cursor vs Codex?

No. Use the same prompt text everywhere. Only the MCP config snippet differs by IDE (Connect IDE tabs). Prompts live on the Connect Agents page under Try these prompts.

Is MetroPanel reading my Cursor chats?

No. The panel only sees API calls made with your token (list apps, deploy ZIP, etc.). Your chat stays in the AI tool.

Can my reseller or admin see my agent token?

They cannot see the secret token value after creation (it is shown once to you). They may still administer the server or account through normal panel roles — that is separate from this feature.

I generated a token but my IDE cannot connect

Confirm the panel URL and token were copied completely
Confirm Node.js 20+ is installed on the computer running the IDE
Confirm the MCP snippet uses npx (or a local path on this computer), not a panel-server path
Confirm the token is not expired or revoked
Try the Advanced → curl example to test the API from your machine

Does this replace File Manager?

No. Agents still cannot open File Manager or Terminal. For publishing a whole site they use ZIP / Git deploy (scoped replace of the app deploy root). Use File Manager yourself for small one-off edits.

How is ZIP deploy safer than giving Terminal?

Deploy only unpacks into that app’s folder (with ZIP safety checks). The AI cannot run arbitrary shell commands or browse the whole home directory. Risk is limited to overwriting that app — still use Manage only when needed, and revoke tokens.

Who is this for?

Hosting end users who want AI tools to help operate their own account and put custom sites online. Server admins using WHMCS should keep using Security → API Tokens for billing.

Will MetroPanel make “host this site” even easier later?

Yes — planned for a future release with MetroBrain (in-panel / guided AI, propose → confirm), reusing the same install/deploy tools. Today the flow already works via external IDEs + Connect Agents prompts (“build the site” → “host on MetroPanel”). See product blueprint: PRODUCT-BLUEPRINT.html#metrobrain-host-flow.