Why mcp-remote instead of pointing Codex straight at the URL?

Codex speaks stdio to its MCP servers and the moodspec endpoint is HTTP. mcp-remote is the standard bridge between the two — there is nothing moodspec-specific about it.

Does the same config work for the CLI and for cloud tasks?

The server block does. The token should not be shared between them — keep it in each environment's secrets so revoking one does not break the other.

Can Codex write to the canvas?

Only through propose_change, which is a Business scope. Every proposal waits for an owner to approve it; there is no direct write tool.

How many calls does a session make?

Usually one get_canvas at the start, then targeted calls for typography or palette as the work needs them. Pro allows 600 an hour per token.

Does the canvas have to be public?

No. The endpoint is private per canvas and only answers to a valid bearer token.

← All integrations

Codex + moodspec

Setup · about 2 minutes

Copy your endpointConnect agent on the canvas and copy the URL and token.
Edit config.tomlAdd the mcp_servers block below.
VerifyRun codex mcp list — moodspec should report connected.
Use itMention the canvas in your task description; Codex queries it for design decisions.

~/.codex/config.toml

[mcp_servers.moodspec]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.moodspec.app/c/brand-soul"]
env = { MOODSPEC_TOKEN = "msk_live_••••" }

Works headless

Because the canvas lives behind a URL, scheduled or cloud Codex runs get the same taste as your laptop — nothing to copy into the repo.

Confirm it is connected

Terminal

codex mcp list

moodspec appears with a connected status. Codex spawns the mcp-remote bridge on demand, so the first call after a config change is slower than the rest.

When it does not work

codex mcp list shows nothing: config.toml is not where Codex looked, or the table header is misspelt — it is [mcp_servers.moodspec], with an underscore. Confirm the file is at ~/.codex/config.toml and that the header matches exactly. TOML ignores an unknown table rather than erroring, so a typo fails silently.
The bridge starts and immediately exits: npx could not fetch mcp-remote — usually no network on the machine, or an npm registry behind auth. Run npx -y mcp-remote with your URL by hand and read the error. Once it runs standalone it will run under Codex.
Cloud runs fail while the CLI works: MOODSPEC_TOKEN is set in your shell profile, which a cloud run never loads. Set the token in the cloud environment's own secrets rather than inlining it in a committed config.
401 revoked partway through a long run: A token can be revoked from canvas settings at any time, and a revoked token fails on the next call rather than at startup. Issue a fresh token and restart the run. The endpoint is unchanged; only the bearer is.

Questions

Why mcp-remote instead of pointing Codex straight at the URL?: Codex speaks stdio to its MCP servers and the moodspec endpoint is HTTP. mcp-remote is the standard bridge between the two — there is nothing moodspec-specific about it.
Does the same config work for the CLI and for cloud tasks?: The server block does. The token should not be shared between them — keep it in each environment's secrets so revoking one does not break the other.
Can Codex write to the canvas?: Only through propose_change, which is a Business scope. Every proposal waits for an owner to approve it; there is no direct write tool.
How many calls does a session make?: Usually one get_canvas at the start, then targeted calls for typography or palette as the work needs them. Pro allows 600 an hour per token.
Does the canvas have to be public?: No. The endpoint is private per canvas and only answers to a valid bearer token.

MCP is on Pro — see pricing