Set up Codex for Netlify

For the complete documentation index, see llms.txt

Learn different ways to set up Codex for use with Netlify.

This setup guide includes:

several ways to set up your Codex agent for success
common troubleshooting issues and workarounds

Before you begin

Codex installed.
Node 22 or higher installed.

We recommend you have a project to test deploying. This can be an existing project or a new project.

You can start setting up Codex for Netlify without a Netlify personal account or Netlify team workspace. When needed, Codex can prompt you to log in or set up a Netlify account.

Quick setup with `netlify.ai`

Equip your agent with the latest Netlify context, including agent skills:

fetch https://netlify.ai to help me deploy and build with Netlify using the latest agent skills

You only need to fetch https://netlify.ai during initial setup or when you want Codex to refresh the installed Netlify context. In future sessions, use the installed Netlify skills directly.

When Codex finishes, it should be able to describe your project and how it would deploy it.

If Codex asks you to authorize Netlify CLI access, open the authorization link it provides and complete the login flow. If Codex creates a new deploy or site for you, open the claim link it provides to claim the site in Netlify.

Install Netlify MCP server

You can connect Codex to the Netlify MCP server remotely (a hosted connector) or locally (runs on your machine via npx).

Remote MCP: In Codex, add Netlify’s hosted connector. You authenticate with OAuth and nothing runs locally, which is handy if you don’t want Node processes spawning per session, or if you want the same connection across Codex sessions.
Local MCP: Run this command in your terminal:
Terminal window
```
codex mcp add netlify -- npx -y @netlify/mcp
```
This runs via npx on your machine and can use your local Netlify CLI login and project context directly.

We recommend the remote MCP connector for most setups. Local MCP is mainly useful if remote MCP connectors aren’t allowed in your environment.

To add the local Netlify MCP server in the app, use the following settings:

Field	Value
Name	`netlify`
Command to launch	`npx`
Arguments	`-y`, `@netlify/mcp`

After the MCP server starts, authorize Netlify if prompted. Then ask Codex to confirm the connection with a test call:

Use the Netlify MCP server to run a test call to get-user.

Learn more about Netlify’s MCP server.

Next steps

As a next step, consider deploying your project or building custom experiences with Netlify primitives.

Deploying

When you’re ready to deploy a production version or draft version of your site or app, tell Codex, which can help you do this. We recommend deciding how you want to deploy first.

Ways to test deploying	Description	CLI command
draft deploy	Safe way to test a deploy without deploying to production	`netlify deploy`
production deploy	Deploy to the live production version of your site or app, most often used as the first deploy for a new project and less often once the project is live on Netlify	`netlify deploy --prod`
anonymous deploy	Most often used for temporary projects or for AI agents testing flows, this command can generate a temporary live URL. You have one hour to claim ownership of the deployed project by logging in or creating a Netlify account. After one hour, unclaimed projects are removed.	`netlify deploy --allow-anonymous`

Learn more about deploy types and the CLI:

Building with primitives

After confirming you can deploy successfully, consider building custom experiences with Netlify’s agent skills.

You can try some of these prompt ideas based on the capabilities of Netlify’s primitives:

“Add a new contact page to my site using Netlify Forms with spam protection”
“Convert this Express endpoint into a Netlify Function”
“Implement an Edge Function that geolocates users and rewrites to localized content”
“Check my netlify.toml configuration for issues”

Troubleshooting Codex setup for Netlify

Get help with some common troubleshooting issues.

Authentication issues

If you’re having issues logging in to Netlify, consider whether your company has enabled Netlify SSO and whether you need to use a different work login or personal user ID or email to log in.

For more help authenticating to Netlify, check out our docs on CLI auth.

You can prompt Codex to help you log in, or use the CLI command netlify login.

If your project doesn’t contain sensitive information, you can try running an anonymous deploy using the Netlify CLI to get a test deploy that will expire within an hour unless it is claimed.

Deploy issues

You can try running an anonymous deploy to isolate some deploy issues, such as auth issues. We only recommend this if your project doesn’t contain sensitive information, since the anonymous deploy generates a temporary URL that expires within an hour unless it’s claimed.

Netlify CLI issues

To check that Netlify CLI is installed:

netlify status

To test your connection is to the right existing Netlify account:

netlify login

To directly install latest version of the Netlify CLI, run this command in your terminal:

npm install -g netlify-cli

Then confirm your setup with netlify --help or just netlify.

Netlify skills don’t install or seem outdated

Try installing or referencing Netlify skills directly from the Netlify agent skills repository.

# Install Netlify skills for Codex
npx -y skills add netlify/context-and-tools --skill '*' --yes --agent codex

If you confirm you have the latest agent skill, you can ask Codex to use it directly in a session using $<skill-name> or a URL to the skill file in Netlify’s agent skills repository.

Node issues

For the best experience, we recommend using Node 22 or higher.

In your terminal, run node --version to check your current version.

If you have a Node version manager like nvm, you can run nvm install 22 to install Node 22 and nvm use 22 to use it.

Did you find this doc useful?

Your feedback helps us improve our docs.