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:

  1. Add a new MCP connector in your client and paste the server URL: https://thecodexapps.com/api/mcp
  2. Your client discovers our authorization server automatically (RFC 9728 + RFC 8414 metadata) and opens https://thecodexapps.com/oauth/authorize
  3. Sign in and approve the requested scopes on the consent screen
  4. 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_service change nothing without confirm: 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 the billing scope. 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.