How to connect Macaly Cloud MCP with Codex

Create a new, EMPTY Macaly app that YOU will write the code for. Macaly provides the infrastructure (git repo, sandbox, build, hosting) — its own coding agent is NOT started, no AI build runs, and the conversation starts with no messages. Projects use the platform's default template: TanStack Start (React 19) + Vite + Tailwind, with Convex as the backend (provisioned via the setup-convex-db skill when needed). The response includes a briefing (stack, non-negotiable boundaries, conventions, workflow) — read it before writing any code. Returns a chatId immediately; the workspace bootstraps in the background and you can start writing right away (a first write on a cold workspace just takes ~20-30s longer). Moving a project from Lovable? Create the app, then read skill_info(chatId, 'migrate-from-lovable') before copying anything. With kind "scratchpad" it instead returns your hidden scratchpad for utility work (skills, one-off scripts, file processing): one per team, reused across calls, never listed in list_projects or the dashboard, and never publishable.

Project status snapshot: preview build state, preview URL, newest publish status, liveUrl (the URL to give the user for the version that is live now), and active claims. Pass includeBriefing: true to also get the project briefing (stack, boundaries, conventions, workflow and working rules) — create_app already returned it, so leave it off when polling, but pass it once when you continue an existing app in a new conversation. Decide your next action: agentTurnPhase='idle' → write_file/edit_file/delete_file to make changes (each call commits immediately; no need to wait for anything after create_app). agentTurnPhase != 'idle' → Macaly's own agent is working on this app; do NOT write, retry later. activeEditor set → another external editor wrote recently (sameUser: true means another app connected to the same Macaly account, which shares this worktree). After your last write → typecheck with bash ".sandbox/check-errors --strict"; on problems → get_logs. previewUrl serves content once previewBuildStatus='succeeded' (builds run automatically after bootstrap and shortly after your last write). Use publish_app only when the user asks to go live; then poll get_deployment.

Duplicate an app (with its history) into a fresh one you can edit independently — the same as 'Duplicate' in the Macaly dashboard. Returns the new app's chatId. This provisions a workspace, so it can take a while.

List the Macaly teams you can act on. Use this to discover the teamId to pass to create_app when connected via OAuth (API keys are scoped to one team and never need it).

List the Macaly apps of a team, most recently updated first (paginated; pinned apps come back in full on the first page only, and later pages return an empty pinnedProjects). Use it to find the chatId of an existing app to inspect or edit — pass it to get_project, list_files, read_file and the write tools.

Read the app's conversation history. The first page holds the newest messages and nextCursor pages backward to older ones; within a page, messages are in chronological order (oldest first). Use it to catch up on the chat before making changes — what the user asked for and what was built so far. Returns each message's role, plain text and creation time plus a tool-call count; internal build traces and tool payloads are omitted to keep responses small.

List the project's source file paths (paginated array of strings). Use read_file to fetch a file's contents.

Read one project file by path. Pass `path` exactly as list_files returned it. A missing path is a NOT_FOUND error. Pass startLine and endLine (1-based, inclusive) to read only part of a large file; every response reports totalLines. Responses are capped at 100000 characters: a cut response has truncated: true and nextStartLine, the line to read next.

Write one file and commit it immediately: the full content replaces the file at that path, producing one git commit and one history entry per call. To change part of an existing file, use edit_file instead of sending the whole file. Takes a few seconds (acquires the project sandbox). Rejected while Macaly's own agent is working (CHAT_CLAIMED_BY_AGENT). Rejects protected paths (.macaly/, .sandbox/, .git/, node_modules/, package-manager config), path traversal, package.json lifecycle scripts, and removing <MacalyBridge> from src/routes/__root.tsx. Max 256KB per file. After your last write, typecheck with bash ".sandbox/check-errors --strict"; the preview rebuilds automatically. TEXT ONLY — this is source code, not a file transfer. Never write an image, video, font or other binary here, base64-encoded or otherwise: it bloats the repo and the commit, and the app cannot use it. Media belongs in the media library — upload_file takes a public URL or a file from your own disk, or call list_media for a link the user can drop a local file into — then reference the returned public URL from the code.

Change part of one existing text file and commit it immediately: each edit replaces oldText with newText, in order, against the file's current content (uncommitted command changes included). oldText must match the file exactly, including spaces and line breaks, and must match one place unless replaceAll is true. All edits apply together or none does: a missing or ambiguous match (EDIT_NO_MATCH / EDIT_AMBIGUOUS_MATCH) changes nothing. Produces one git commit and one history entry, and the same claiming, protected-path, size and preview rules as write_file. Up to 20 edits per call. After your last change, typecheck with bash ".sandbox/check-errors --strict".

Delete one file and commit the deletion immediately (one git commit and one history entry per call). Same claiming and protected-path rules as write_file.

Run a shell command in the app's sandbox (project root), e.g. to install dependencies with npm: bash(chatId, "npm install zod"). A full shell — pipes, chaining and redirection all work. This is also how you EXECUTE skills: the sandbox has $MACALY_API_TOKEN, $MACALY_BASE_URL and $MACALY_CHAT_ID set and the skill scripts under .macaly/skills/, so the commands a skill_info guide documents run verbatim here. TYPECHECK after your last write by running ".sandbox/check-errors --strict" (tsc + CSS + dev-server + Convex errors, then a summary; it exits non-zero when TypeScript or CSS fails; give it timeoutSeconds: 120 — the script is always present, this tool maintains it). Prefer write_file/edit_file/delete_file for source edits (they commit with a history receipt and enforce the protected-path rules). Note: file changes a command causes (package.json, lockfile, .env.local from setup scripts) are committed together with your NEXT write_file, edit_file or delete_file, so a bash-only session leaves an uncommitted worktree — run one of them (or install deps before writing the code that uses them) to persist them. Git commits a command makes are saved when it ends. Do not save generated or downloaded media (images, audio, video) in public/: every preview build uploads public/ again. Upload media with upload_file and use the returned URL. A command can have up to 32,000 characters and run for up to 240 seconds. Long output returns only the first 6,000 and the last 6,000 characters, so write large output to a file and read it in parts.

Fetch real logs for the project, head/tail-truncated. log_type: 'build' = latest preview build (status, failure reason, build output errors); 'dev_server' = tail of the live sandbox dev-server log (boots the sandbox if needed, ~20s cold); 'deploy' = the newest publish attempt, or the one named by deploymentId, and its build stderr from the hosting provider.

Get the app's LIVE preview URL to share with the user. Call it at the end of every turn that changed the app, after the preview rebuild succeeds (get_project reports previewBuildStatus), even when an earlier link is still valid: the call tells Macaly that your turn is finished. Pass path to open a subpage directly (e.g. "/pricing") and give the user that link instead of telling them where to navigate. It never triggers a build; it creates a temporary, exact-app access link valid for three hours.

Read a Macaly skill's guide (its SKILL.md): what the capability is, plus ready-to-run curl commands for its platform endpoint and the code patterns to apply. Call this BEFORE implementing a platform capability (database, auth, payments, AI, media, search, integrations). Then EXECUTE the guide with the bash tool: its curl commands and scripts run verbatim there (the sandbox has the $MACALY_* credentials they reference); app-runtime patterns the guide shows go into the app with write_file. Example: for a database, skill_info(chatId, "setup-convex-db"), then run the setup script it documents via bash. Available skills: ai-classification, ai-image, analytics, api-domain, apify-scraping, apify-scraping/google-maps-business, apify-scraping/linkedin-profile, app-files-upload, assets-list, assets-upload, auth-otp, beautiful-landing-page, conversation-memory, convex-agent, convex-best-practices, convex-contract-migration, convex-performance-audit, create-favicon, database-crud, db-client-loading-pattern, db-security-pattern, db-ssr-seo, debugging-strategy, deploy-convex-app, docx, domain-check, email-and-password-auth, expose-mcp, frontend-design, get-conversation, google-auth, icon-search, integrations, internet-search, live-site-logs, llm-usage, lovable-rebuild, macaly-info, migrate-from-lovable, music-generation, payments, pdf, pdf-insight, platform-agent-notification, pptx, reapply-convex-env, recreate-from-url, rename-chat, rename-macaly-subdomain, restart-dev-server, security-review, seo-audit, seo-metadata, set-env-vars, setup-convex-db, simple-admin-blog, stock-photo-search, stripe-checkout, stripe-checkout-branding, stripe-checkout-page, stripe-coupons, stripe-setup-sandbox, telegram-bot, test-convex-functions, test-react-nextjs, test-react-tanstack, text-to-voice, transactional-emails, translations, type-error-context, variants, video-generation, view-logs, voice-to-text, web-browser, webpage-fetch, webpage-screenshot, work-with-files, xlsx, youtube-insight.

Put a file (image, video, document, …) into the app's media-asset storage and get back its permanent public URL — usable directly in the app's code or fetchable into the sandbox via bash. Max 1 GB. Two sources, pick one: 1. sourceUrl — a publicly reachable http/https URL. The server imports it; the returned url is live immediately. 2. fileSize + contentType (+ localPath) — a file on your own machine or in the project sandbox. The result contains the final url plus a presigned uploadUrl and a ready curlCommand. Run curlCommand where the file is: in your own local shell for a file on your machine, or with this server's command tool for a file in the project sandbox. When it exits 0 the url is live. fileSize and contentType must match the file exactly, or storage rejects the PUT. This needs a shell with network access to the returned uploadHost; if curl cannot connect or fails with HTTP 403 and a proxy note, follow the returned nextStep. Never paste file contents or base64 into a tool argument. Without a local shell and without a public URL, use list_media — it returns a link to the app's media library for the user to drop the file into. Do not upload the user's file to an unrelated third-party host to get a URL.

List the files in the app's media library — everything uploaded by the user or added with upload_file — so you can reference their public URLs from the app's code. Check here before asking the user for an image; they may already have uploaded it. The response also includes an uploadUrl: a link to this app's media library. When the user has a file only on their computer and you cannot send it yourself with upload_file (no local shell, or the upload host is blocked), send them that link, ask them to drag the file in, and call this tool again to pick it up. No tool can accept raw bytes.

Publish the app to production (make it publicly live at its macaly.app URL). Only call this when the user explicitly asks to go live. Requires at least one committed edit. Asynchronous — poll get_deployment with deploymentId set to the id this tool returns until status is READY or DELIVERED (or ERROR, then check get_logs with log_type 'deploy' and the same deploymentId). Then give the user liveUrl from get_deployment. DELIVERED means partner publishing is complete; report the project as published without inventing a site URL.

Get the newest publish attempt of the app, or the one named by deploymentId: status (QUEUED/BUILDING/READY/DELIVERED/ERROR), deployment url and connected domains. liveUrl is the URL of the version that is live now; give the user liveUrl, not url. During a re-publish, liveUrl keeps the previous version until the new one is READY. Poll after publish_app with its id until READY, DELIVERED or ERROR. On ERROR, call get_logs with log_type 'deploy' and the same deploymentId for the build stderr. DELIVERED means partner publishing is complete; no further status check is required. Do not invent a site URL.

Connect a custom domain to a published app. Returns the DNS records to configure at your registrar; the domain goes live once DNS verifies. Requires a plan that allows custom domains.