Codex + xCloud
Manage Your Hosting from Codex with xCloud
Codex is OpenAI's coding agent, which runs in your terminal and in an IDE extension. Connected to xCloud through the MCP server, it deploys repositories, checks servers and sites, and diagnoses failures from the same session you write code in.
- One codex mcp add command
- Or a config.toml entry
- Free with every xCloud account
YouDeploy github.com/acme/shop to my Frankfurt server on a staging hostname.
git_detectread-only
AgentNode.js app on main, build npm run build, start npm start. Dry run passed. Create shop-staging on Frankfurt?
YouYes.
servers_sites_git_createneeds approval
AgentDeployed. SSL issued and the staging URL answers 200.
. Keep a human in the loop: xCloud stops and asks before anything that creates, deploys, updates, reboots, deletes or buys.
Setup
How Do I Connect Codex to xCloud?
Point Codex at the xCloud MCP server, approve access in your browser, then ask. The whole thing takes a couple of minutes. The xCloud Agent Skills are an optional layer on top of that connection: they teach the agent the workflows, they do not replace it.
Add the xCloud MCP server
Run this in your terminal. This form comes from xCloud's connect guide; OpenAI's Codex page documents codex mcp add for local commands, so if your version rejects --url, use the config.toml step below.
codex mcp add xcloud --url https://app.xcloud.host/mcpOr write it in config.toml
Codex reads ~/.codex/config.toml. Add a table for the server with its url. A Streamable HTTP server needs only the url, and the same file is where you set a bearer_token_env_var if you use an API key instead of OAuth.
[mcp_servers.xcloud] url = "https://app.xcloud.host/mcp"Sign in and check
Run the login command, approve the teams and choose Read-only or Full access in the browser, then type /mcp in Codex to see xcloud and its tools. Optional: Codex is also listed for the xCloud Agent Plugins package, which adds the xCloud skills.
codex mcp login xcloudCheck it worked
codex mcp login signs you in with OAuth, and Codex supports dynamic client registration. For a machine without a browser, set bearer_token_env_var in config.toml to the name of an environment variable holding a token with the mcp:invoke scope plus the read or write abilities it needs.
Who am I on xCloud?
Three surfaces
Which Way Should I Connect Codex to xCloud?
The MCP server exposes one tool per customer-facing xCloud operation and leaves out eleven internal ones that only the Public API carries; the skills add workflow know-how on top of an MCP connection and, on their own, only read access. All three are free with every account and differ in what you set up and what holds the credentials.
| xCloud MCP server | xCloud Agent Skills | Public API | |
|---|---|---|---|
| Terminal needed | No (recommended for Codex) | Yes for the plugin or ClawHub install | Yes |
| Authentication | OAuth sign-in, or an API key with mcp:invoke plus read or write abilities (recommended for Codex) | The MCP connection, or a read-scoped API token | API token with scoped abilities |
| What it adds | One tool per customer-facing xCloud operation (188 today) (recommended for Codex) | Workflow know-how: routing, dry run, confirm, poll, diagnose | Raw REST for your own code |
| Changes to your infrastructure | Yes, after confirmation (recommended for Codex) | Only through a connected MCP tool, after confirmation | Yes, with write scopes |
| Best for | Most people; every MCP client (recommended for Codex) | Agents that run shell commands and read skills | CI jobs, dashboards and long-running loops |
Background
What Is Codex?
Codex is OpenAI's coding agent. In the terminal it reads your repository, edits files, runs commands and works through multi-step tasks, and it is also available as an IDE extension. You decide how much it does without asking.
Codex speaks the Model Context Protocol. You register a server with codex mcp add or by writing a [mcp_servers.xcloud]-style table in ~/.codex/config.toml, and for servers that need a sign-in you run codex mcp login. Typing /mcp in Codex lists the connected servers and their tools. xCloud runs a remote MCP server at https://app.xcloud.host/mcp that fits this format.
Once the server is registered, a deploy no longer means switching to a dashboard. You push, ask Codex to deploy, and it detects the app, previews the site, waits for your approval and checks the live URL before it reports back.
Why Codex with xCloud?
Deploy from where the code is
Codex already knows your repository. Ask it to deploy and it hands the URL, branch and build settings to xCloud, dry-runs the site and asks once before creating anything.
Config you can keep in a file
The connection is a few lines in ~/.codex/config.toml. You can review it, copy it to another machine and keep tokens out of it by naming an environment variable.
Skills package for Codex too
Codex is listed for the portable Agent Plugins package, which carries the xCloud skills and the MCP connection. The skills teach it when to dry-run, how to confirm and how to diagnose a failed deploy.
Guides
What Can Codex Do on xCloud?
One guide per hosting job, each with the Codex setup, the xCloud tools involved, a settings reference, example prompts and the limits that apply.
- Deploy from Git with CodexTurn a GitHub, GitLab or Bitbucket repository into a live site on a server you already have.
- Run Docker apps with CodexRun a Dockerfile or Docker Compose app on a Docker server, keep it backed up and recover it when a deploy fails.
- Install one-click apps with CodexPick an app from the xCloud catalogue, check it fits your server, install it and get the login details.
- Manage WordPress with CodexKeep WordPress sites updated, scanned and healthy, and create new ones, by asking in plain words.
- Back up and stage sites with CodexCheck that your sites are backed up, take a backup before a risky change, and open a staging copy to test it on.
- Manage SSL and domains with CodexCheck a site's certificate and DNS, install or renew HTTPS, and see which domains point at it.
- Manage servers with CodexSee how your servers are doing, change services and runtimes, tighten security and reboot with proof it worked.
- Troubleshoot a broken site with CodexFind out why a site returns a 500, 502 or 503, shows a critical error or has stopped answering.
- Speed up a slow site with CodexFind out why a site is slow, from real numbers, and learn which fix is a dashboard switch.
- Secure sites and servers with CodexFind vulnerable sites, manage server firewall rules and banned IPs, and see which protections are on.
Example prompts
What Can You Ask Codex to Do on xCloud?
Type these as written and swap in your own site and server names. Reads and routine actions such as backups, cache purges, PageSpeed scans and vulnerability scans run straight away; creating, deploying, updating, rebooting, deleting, buying or starting a broken-link scan stops and asks first.
Deploy https://github.com/acme/shop to my Frankfurt server and show me the dry run before you create anything.Update all plugins on example.com, but take a backup first and confirm the homepage still loads.The last deploy of the API site failed. Diagnose it, fix the build command and retry on the same site.Renew the SSL certificate for shop.example.com and tell me when it expires now.Audit example.com: is it up, is SSL healthy, any vulnerabilities and how is performance?Good to know
- OpenAI's Codex page shows codex mcp add for local commands. If the --url form is rejected by your version, use the [mcp_servers.xcloud] table in config.toml, which the page does document.
- Run codex mcp login xcloud after adding the server, or the tools stay unavailable. Type /mcp in Codex to confirm xcloud is listed.
- Never put an API token in config.toml itself. Use bearer_token_env_var and set the variable in your shell or secret store.
More prompts, grouped by job: What you can ask xCloud MCP to do.
Codex and xCloud: Frequently Asked Questions
Short answers about connecting Codex, what it may change and what it costs.
How do I connect Codex to xCloud?
Run codex mcp add xcloud --url https://app.xcloud.host/mcp, or add a [mcp_servers.xcloud] table with that url to ~/.codex/config.toml. Then run codex mcp login xcloud, approve the access in your browser and ask who am I on xCloud.
Where does Codex keep its MCP configuration?
In ~/.codex/config.toml, under one [mcp_servers.xcloud]-style table per server, named after the server. For a Streamable HTTP server such as xCloud the table needs a url. The codex mcp add command writes the same configuration for you.
Does Codex need an xCloud API key?
Not when you sign in with codex mcp login, which uses OAuth. A key is for a machine without a browser. Create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things, put it in an environment variable and name that variable in bearer_token_env_var in config.toml.
How do I check that xCloud is connected in Codex?
Type /mcp in Codex to list connected servers and their tools, then ask who am I on xCloud. If xcloud is missing or shows no tools, run codex mcp login xcloud again.
Can Codex change my servers without asking?
Not for the operations xCloud gates. Reads and routine actions such as backups, cache purges, PageSpeed and vulnerability scans run without a prompt. Creating a site or server, deploying, updating plugins, rebooting, deleting or buying is refused by xCloud unless the call carries an explicit confirmation, so Codex asks you first.
Can I install the xCloud skills in Codex?
Yes. Codex is listed for the portable Agent Plugins package from the xcloud-agent-skills GitHub releases, which bundles the nine xCloud skills and the MCP connection. The MCP connection alone already gives Codex every xCloud tool.
Can Codex work across several xCloud teams?
Yes. On the approval screen you tick every team the connection may act on, and you name the team in your request. A site on a team you did not tick comes back as not found, so reconnect and tick it.
Is it free to use Codex with xCloud?
The xCloud side is free: the MCP server, the skills and the Public API are included with every xCloud account, including the free plan. Codex itself is billed by OpenAI under your plan or API usage.
Other agents
Also Works With
The same xCloud account, the same operations, a guide for each client.
- Claude CodeAnthropic's terminal coding agent. One claude mcp add command, plus the xCloud skills plugin with nine skills on top.
- ClaudeAnthropic's chat assistant on the web and desktop. Add xCloud as a custom connector, no terminal needed.
- Claude CoworkAnthropic's desktop agent for delegated work. Add the xCloud connector, then hand off hosting jobs.
- CursorThe AI code editor. One mcp.json entry with the compact URL, because Cursor stops at 40 tools.
- OpenCodeThe open-source terminal coding agent. One remote MCP entry, then opencode mcp auth xcloud.
- Hermes AgentNous Research's agent with memory and a built-in scheduler. An mcp_servers entry in config.yaml and one login.
- OpenClawThe open-source agent runtime with chat apps and automations. ClawHub skill plus the MCP client.
- WindsurfThe Cognition editor, now Devin Desktop. devin mcp add for the Devin Local agent, a serverUrl entry for legacy Cascade.
- GitHub CopilotCopilot agent mode in VS Code. One .vscode/mcp.json entry, or the Agent Plugins package.
- Gemini CLIGoogle's terminal agent. One gemini mcp add command, OAuth found automatically.
- ChatGPTOpenAI's chat assistant. A developer-mode app with the xCloud MCP URL and OAuth.
- ChatGPT dotsOpenAI's always-on agent in ChatGPT. Uses the xCloud MCP plugin you add in ChatGPT, with custom rules and scheduled tasks.
- GrokxAI's terminal agent, Grok Build. One grok mcp add command or a config.toml entry.
- Grok BotxAI's always-on Bots on a cloud computer. One Remote HTTPS MCP plugin, OAuth sign-in, routines on a schedule.
- KiroAWS's agentic IDE. One url entry in .kiro/settings/mcp.json, plus the portable xCloud Agent Plugins package.
- AntigravityGoogle's agentic IDE. One serverUrl entry in mcp_config.json and a browser sign-in.
- ZedThe Zed editor's Agent Panel. One context_servers entry in settings.json and a browser sign-in.
Run Your Hosting from Codex
xCloud MCP, the Agent Skills and the Public API are free with every account. Connect once and ask.