MCP server (AI assistants)
TheCodexApps ships a remote MCP server so your AI assistant can deploy and manage your services with exactly the same authorization, limits and billing checks as the panel. Ask for a deploy, a restart, the latest logs or your wallet balance — the assistant calls the same functions the panel uses.
Server URL: https://thecodexapps.com/api/mcp
Authentication
MCP requests authenticate with an API key, created under Settings → API & MCP (the full key ws_live_… is shown exactly once; we store only its SHA-256 hash). Send it as a bearer token:
Authorization: Bearer ws_live_YOUR_KEY
Keys carry scopes, and every tool checks them:
| Scope | Allows |
|---|---|
read |
List and inspect everything — always included. |
write |
Manage: env vars, power actions, redeploys, custom domains, delete (with confirm). |
deploy |
Create new services, apps and databases — free inside a package, or a plan order with an invoice. |
billing |
Pay orders from your wallet balance. |
Connector clients that cannot keep a secret (Claude.ai, ChatGPT connectors, desktop apps) connect with OAuth instead — see OAuth (connector clients) below.
OAuth (connector clients)
Claude.ai, Claude Desktop connectors, ChatGPT connectors and other OAuth-capable MCP clients connect by URL only — no API key:
- Add a new MCP connector in your client and paste the server URL:
https://thecodexapps.com/api/mcp - Your client discovers our authorization server automatically (RFC 9728 + RFC 8414 metadata) and opens
https://thecodexapps.com/oauth/authorize - Sign in and approve the requested scopes on the consent screen
- The client exchanges a one-time code with PKCE (S256) for short-lived access tokens and refreshes them automatically
On the consent screen you choose exactly what the app may do: read is always included, write and deploy are pre-checked when requested, and billing — which lets the assistant pay orders from your wallet balance — is off unless you turn it on.
Everything a connected app does runs through the same tools, scope checks, quotas and billing rules as the panel, and every call is recorded in your Activity log. Manage or disconnect connected apps any time under Settings → API & MCP → Connected apps; disconnecting signs the app out immediately.
Connect your client
Replace ws_live_YOUR_KEY with a key from Settings → API & MCP. The settings page shows all of these snippets with a freshly created key filled in.
Claude Code
claude mcp add --transport http thecodexapps https://thecodexapps.com/api/mcp --header "Authorization: Bearer ws_live_YOUR_KEY"
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"thecodexapps": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://thecodexapps.com/api/mcp", "--header", "Authorization: Bearer ws_live_YOUR_KEY"]
}
}
}
Claude Desktop's built-in connectors can also add the server URL directly with OAuth — no key needed (see OAuth).
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"thecodexapps": {
"url": "https://thecodexapps.com/api/mcp",
"headers": { "Authorization": "Bearer ws_live_YOUR_KEY" }
}
}
}
Or use the one-click Add to Cursor button on the settings page.
VS Code
Add to .vscode/mcp.json:
{
"servers": {
"thecodexapps": {
"type": "http",
"url": "https://thecodexapps.com/api/mcp",
"headers": { "Authorization": "Bearer ws_live_YOUR_KEY" }
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"thecodexapps": {
"serverUrl": "https://thecodexapps.com/api/mcp",
"headers": { "Authorization": "Bearer ws_live_YOUR_KEY" }
}
}
}
ChatGPT and other connectors
Add the connector URL https://thecodexapps.com/api/mcp, then sign in and approve the requested scopes — no API key needed. Clients without OAuth support can use an API key as the bearer token instead.
Tools
| Tool | Scope | What it does |
|---|---|---|
whoami |
read | Your email, name, wallet balance, email-verified flag, granted scopes and active packages with their remaining pool. |
list_locations |
read | Enabled locations and whether they currently have stock. |
list_plans_and_packages |
read | Plans per product type with prices and locations, resource packages, and your own package subscriptions with remaining pool. |
list_templates |
read | The one-click app catalog with search, category filter and paging. |
list_services |
read | Your services: id, name, type, status, URL, plan or package, resources. |
get_service |
read | One service in detail: status, URL, resources, domains, env var names and the last deployments. |
get_deploy_logs |
read | Build output of the latest or a given GitHub deployment. |
get_runtime_logs |
read | Recent container logs (1–500 lines). |
get_wallet_balance |
read | Wallet balance and unpaid invoices with payment URLs. |
deploy_app_from_template |
deploy | Deploy a one-click app into a package (free) or on a plan (invoice). |
deploy_from_github |
deploy | Deploy a GitHub repository (public, GitHub App or deploy key) into a package or on a plan. |
create_database |
deploy | Create a managed database (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, ClickHouse). |
set_env_vars |
write | Upsert up to 50 environment variables, with an optional redeploy. |
redeploy_service |
write | Start a new deployment of a GitHub app. |
restart_service |
write | Restart a running service's container. |
stop_service |
write | Stop a running service's container. |
start_service |
write | Start a stopped service's container. |
add_custom_domain |
write | Claim a custom domain and get the DNS records to create. |
delete_service |
write | Delete a service permanently — requires confirm: true plus the exact service name. |
Safety model
- Confirm before spend. The create tools and
delete_servicechange nothing withoutconfirm: true. Called without it, they return a preview: price, billing cycle, coupon, wallet balance, whether the invoice would be paid from balance, and whether the allocation fits your package pool. - Billing is a separate scope. Even with
confirm: true, an invoice is only paid from your wallet when the key has thebillingscope. Otherwise the order is left as an unpaid invoice with a payment link for you. - Package pool is enforced. Deploys into a resource package are free but check the remaining CPU/RAM/disk pool first, exactly like the panel.
- Least privilege. Give each key only the scopes it needs; a read-only key can never change anything.
- Full audit trail. Every MCP call is recorded in your Activity log.
Example prompts
- "Deploy my GitHub repo acme/web on branch main into my Starter package with 1 GB RAM."
- "Show the last deploy logs of api."
- "Set DATABASE_URL on api and redeploy."
Rate limits
MCP requests are limited to 120 per minute per key, the same budget as the REST API (counted separately). Tool results are bounded: long build logs are tailed to the last 20,000 characters.
Troubleshooting
- 401 Unauthorized — the key is missing, malformed, invalid, revoked or expired. Create a fresh key under Settings → API & MCP. For connected apps, disconnect and reconnect the app so it gets fresh tokens.
- "This key is missing the … scope" — the tool needs a scope the key does not have. Create a key with that scope, or ask the assistant for a read-only alternative.
- 429 Too many requests — you hit the per-key rate limit. Wait for the retry window; if it happens often, spread calls out or use additional keys.