From 74a5800993f247c5c331b53e6669b2593fc75139 Mon Sep 17 00:00:00 2001 From: Dan Lister Date: Mon, 10 Nov 2025 10:45:30 +0000 Subject: [PATCH 1/2] Add OpenAI Codex setup documentation to MCP reference --- .../reference/developer-mcp/README.md | 1 + .../developer-mcp/host-setup/README.md | 5 ++ .../developer-mcp/host-setup/openai-codex.md | 62 +++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 16/umbraco-cms/reference/developer-mcp/host-setup/openai-codex.md diff --git a/16/umbraco-cms/reference/developer-mcp/README.md b/16/umbraco-cms/reference/developer-mcp/README.md index fb6f053f792..4941cc58c64 100644 --- a/16/umbraco-cms/reference/developer-mcp/README.md +++ b/16/umbraco-cms/reference/developer-mcp/README.md @@ -97,6 +97,7 @@ Each MCP-compatible host application has its own setup process. Below you can fi - [Claude Code](./host-setup/claude-code.md) - [GitHub Copilot](./host-setup/github-copilot.md) - [Cursor](./host-setup/cursor.md) +- [OpenAI Codex](./host-setup/openai-codex.md) Although the details vary slightly, the general pattern is the same across all hosts: diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/README.md b/16/umbraco-cms/reference/developer-mcp/host-setup/README.md index 16012935c45..fca9378898e 100644 --- a/16/umbraco-cms/reference/developer-mcp/host-setup/README.md +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/README.md @@ -19,3 +19,8 @@ Getting started with Cursor. ## [GitHub Copilot](./github-copilot.md) Getting started with GitHub Copilot. + +## [OpenAI Codex](./openai-codex.md) + +Getting started with OpenAI Codex. + diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/openai-codex.md b/16/umbraco-cms/reference/developer-mcp/host-setup/openai-codex.md new file mode 100644 index 00000000000..093a9faa9ba --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/openai-codex.md @@ -0,0 +1,62 @@ +--- +description: "Host set up for OpenAI Codex" +--- + +# OpenAI Codex Setup + +[OpenAI Codex](https://openai.com/blog/openai-codex) is OpenAI's terminal-first workspace that pairs a shell, editor, and conversational developer agent. With Model Context Protocol (MCP) support, you can connect Codex directly to Umbraco's tools and data so the assistant can work inside your projects. + +## Getting started + +Install the Codex CLI with npm: + +```bash +npm install -g @openai/codex +``` + +Or install the Codex CLI with brew: + +```bash +brew install codex +``` + +### Configure using the Codex CLI + +Add the Umbraco MCP server with the Codex CLI: + +```bash +codex mcp add umbraco-mcp -- npx -y @umbraco-cms/mcp-dev@beta +``` + +**Define configuration values directly** + +If you prefer to keep secrets in your shell session, pass them as environment variables during registration: + +```bash +codex mcp add umbraco-mcp \ + --env UMBRACO_CLIENT_ID="your-id" \ + --env UMBRACO_CLIENT_SECRET="your-secret" \ + --env UMBRACO_BASE_URL="https://your-domain.com" \ + --env NODE_TLS_REJECT_UNAUTHORIZED="0" \ + --env UMBRACO_INCLUDE_TOOL_COLLECTIONS="document,media,document-type,data-type" \ + -- npx -y @umbraco-cms/mcp-dev@beta +``` + +Replace the `UMBRACO_CLIENT_ID`, `UMBRACO_CLIENT_SECRET`, `UMBRACO_BASE_URL`, and `UMBRACO_INCLUDE_TOOL_COLLECTIONS` values with your local connection details. + +This command stores the MCP server as `umbraco-mcp` in your Codex configuration file (typically `~/.codex/config.toml`). + +{% hint style="info" %} +Use the command below at any time to see which MCP servers Codex is currently loading: + +``` +codex mcp list +``` +{% endhint %} + +## Managing tools and tool collections + +When you change the tool set: + +- Update your `.env` file with the tool collections you want (for example `document,media`). +- Repeat the `codex mcp list` command to confirm the server is healthy. From e9b486b62b9a53ac41bd00317670b84ce345f29f Mon Sep 17 00:00:00 2001 From: Dan Lister Date: Wed, 12 Nov 2025 15:46:49 +0000 Subject: [PATCH 2/2] Add OpenAI Codex reference to developer MCP host setup --- 16/umbraco-cms/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index d25333dc885..1c25b7bbe53 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -370,6 +370,7 @@ * [Claude Code](reference/developer-mcp/host-setup/claude-code.md) * [Cursor](reference/developer-mcp/host-setup/cursor.md) * [GitHub Copilot](reference/developer-mcp/host-setup/github-copilot.md) + * [OpenAI Codex](reference/developer-mcp/host-setup/openai-codex.md) * [Best Practice](reference/developer-mcp/best-practice/README.md) * [Example Instruction File](reference/developer-mcp/best-practice/example-instructions.md) * [Creating Media](reference/developer-mcp/best-practice/creating-media.md)