Connect with Codex

From a Mapled project to a site that reads its content from Mapled, in one Codex session — in the terminal or in your editor.

1. Open the site in Codex

Start Codex in the site's repository:

cd my-site
codex

Codex in your editor works the same way: open the repository's folder first.

2. Paste the prompt

In Mapled, open the project → Connect with AI → Copy prompt, and paste it into Codex. Codex runs npx -y @mapled/cli connect --project <id> first.

The command needs the network — to fetch the CLI from npm and to reach Mapled. When Codex runs commands in a sandbox without network access, it asks before running this one; approve it.

3. Authorize

Your browser opens Mapled on the project. Press Authorize. The command writes mapled.json (the project id and the framework — no secrets) and prints Mapled's guide for agents, which Codex follows from here.

4. Approve the plan

Codex reads the code and proposes a plan. You get an email and Mapled shows the plan: the collections and singles with their fields, the records it will import, the files it will change. Press Approve plan.

You don't need to tell Codex you approved: it waits for the decision with npx -y @mapled/cli tool get_setup_run '{"runId":"…"}' --wait and carries on by itself.

5. Let it finish

Codex applies the plan, wires the site as Mapled tells it for your framework, builds it, runs npx -y @mapled/cli doctor, ships the change to the branch the site deploys from, writes MAPLED.md and reports back. Mapled then checks the deployed site; the result is on the run's page in Integrations.

If the site's host needs the delivery key and Codex can't set it there itself, it names the variable and the one place to paste it — the key is on the project's Integrations → Your site.

6. Publish

Open Review & publish in Mapled and press Publish now. From now on, editors change the content in Mapled and publish; the site follows.

Keep Mapled in Codex

Every Mapled tool is available from the shell without any setup: npx -y @mapled/cli tools lists them and npx -y @mapled/cli tool <name> calls one, through the connection connect made.

To make Mapled known to Codex in every project, install the mapled skill:

npx skills add mapledhq/agent-kit -g

To add Mapled as an MCP server instead, use the stdio server with a project token. Create the token in Mapled: Connect with AI → Other ways to connect, type a connection name, press Generate token and copy the token from the config Mapled shows — it is shown only once. Then add the server to ~/.codex/config.toml:

[mcp_servers.mapled]
command = "npx"
args = ["-y", "@mapled/mcp"]
env = { MAPLED_MCP_TOKEN = "mcp_live_…" }

The token is scoped to that one project. Every tool is listed in the @mapled/mcp README.