Connect Codex CLI to Cultup

Use these instructions when a user gives you a Cultup setup message with a cu_setup_ code. Your goal is to exchange it locally, configure Codex CLI, verify the MCP tools, and then help the user schedule through Cultup.

Agents should prefer the compact Markdown version: /codex-instructions.md.

Agent contract

The copied dashboard prompt is intentionally short. This guide is the source of truth for the setup flow. Agents must prefer the static installer script, verify its checksum before running it, never expose the exchanged token, configure Codex MCP with CULTUP_AGENT_TOKEN, verify before scheduling, and never send email or create calendar events without explicit user approval and matching token permissions.

Use codex mcp get cultup to verify the local Codex MCP config.
Use verify_cultup_connection for read-only MCP verification.
Call draft_meeting_link only after verification succeeds.

1. Confirm the setup code and endpoint

The setup message should include:

A one-time Cultup setup code beginning with cu_setup_.
The MCP URL https://api.cultup.com/mcp.
A static setup script URL such as https://api.cultup.com/downloads/cultup-codex-setup.sh.
The expected installer SHA-256 checksum.

If the user provided a setup code but no endpoint, assume https://api.cultup.com/mcp.

2. Verify and run the installer

Prefer the static installer. It exchanges the setup code once, writes the scoped token to a user-level file, creates an environment helper, configures Codex MCP, and verifies codex mcp get cultup. Ask the user for approval before running it because it edits files under ~/.cultup, supported shell startup files, and ~/.codex/config.toml.

curl -fsSLo /tmp/cultup-codex-setup.sh "https://api.cultup.com/downloads/cultup-codex-setup.sh"
printf '%s  /tmp/cultup-codex-setup.sh\n' "INSTALLER_SHA256_REPLACE_ME" | sha256sum -c -
sed -n '1,220p' /tmp/cultup-codex-setup.sh
bash /tmp/cultup-codex-setup.sh --setup-code cu_setup_REPLACE_ME --mcp-url https://api.cultup.com/mcp

3. Manual fallback

If the verified installer cannot run, exchange the setup code manually. Redirect the response to a user-level file and do not print the real token.

mkdir -p ~/.cultup
chmod 700 ~/.cultup
curl -fsS https://api.cultup.com/api/agent/setup/exchange \
  -H "Content-Type: application/json" \
  --data '{"setupCode":"cu_setup_REPLACE_ME","agent":"codex"}' \
  > ~/.cultup/codex-token.json
chmod 600 ~/.cultup/codex-token.json
export CULTUP_AGENT_TOKEN="$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.env.HOME + "/.cultup/codex-token.json", "utf8")).token)')"
codex mcp add cultup --url https://api.cultup.com/mcp --bearer-token-env-var CULTUP_AGENT_TOKEN

4. Verify the connection

First run codex mcp get cultup and confirm that the cultup server is enabled, points at https://api.cultup.com/mcp, and uses bearer_token_env_var = "CULTUP_AGENT_TOKEN".

Then verify through Codex MCP with verify_cultup_connection. This tool is read-only: it confirms authenticated MCP tool execution without creating drafts, sending email, creating calendar events, reserving quota, searching contacts, or calling calendar provider APIs.

The default Codex setup token has Draft Links permission. It can verify and draft scheduling links. Sending email or creating calendar invites requires the user to upgrade token permissions in Cultup settings.

Confirm tool discovery includes the expected Cultup tools. Prefer Codex MCP verification over shell commands. If Codex MCP tool execution is unavailable or cancelled, use MCP HTTP JSON-RPC as a fallback with the CULTUP_AGENT_TOKEN environment variable instead of writing the raw token into the command, approval prompt, chat, repo files, or logs.

In fallback mode, first call tools/list or verify_cultup_connection. Only call draft_meeting_link after verification succeeds.

curl -i -L \
  -H "Authorization: Bearer ${CULTUP_AGENT_TOKEN}" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"codex-setup","version":"1.0.0"}}}' \
  https://api.cultup.com/mcp

The available tools should include scheduling actions such as:

verify_cultup_connection
draft_meeting_link
update_meeting_draft
send_meeting_invite
create_calendar_event
draft_group_meeting_vote
send_group_meeting_vote_invites

5. Use Cultup safely

Extract the meeting details from the user: guest name or email, title, description, duration, date constraints, working hours, timezone, and buffer preferences.

Start with draft_meeting_link unless the user asks to update an existing draft. Show the drafted email or scheduling link before sending anything. Only call send or calendar-event tools after the user clearly approves that action.

6. First test prompt

Use Cultup to draft a test scheduling link only for Example Guest at example.guest@example.com for a 30 minute meeting tomorrow called "Cultup setup test". Do not send any invitation emails or create calendar events.