> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/ai-connector/connect-a-cli-assistant/configure-codex-cli.md). # Configure OpenAI Codex CLI Connect the OpenAI Codex CLI to your Datasentinel MCP server on Linux, sign in, install the Datasentinel Skill, and verify the configuration. This page shows how to wire the [OpenAI Codex CLI](https://learn.chatgpt.com/docs/codex/cli) to your Datasentinel platform on a Linux host: add the **MCP server**, **sign in** once, install the **Skill** that tells the assistant how to use it, and check that everything is connected. The same pattern applies to other MCP-and-Skill-capable assistants. The commands below are specific to the Codex CLI (the `codex` command), OpenAI's open-source terminal coding agent. {% hint style="info" %} The steps below follow OpenAI's documentation, last checked on 6 October 2026. OpenAI changes the Codex CLI often. {% endhint %} ## Before you start * The Codex CLI is installed and you can run `codex` from a terminal. If it is not yet installed, follow the steps below. * Your Datasentinel MCP server is reachable over HTTPS at `https:///mcp`. See [MCP Server Setup](/manual/ai-connector/server-setup/mcp-server-setup.md) if it is not yet running. ## Install the Codex CLI Codex CLI is a native binary (written in Rust) and runs on Linux and macOS. For the full instructions, see OpenAI's [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) guide. Download and run the official installer: ```bash curl -fsSL https://chatgpt.com/codex/install.sh | sh ``` For other installation methods, see the [Codex CLI installation guide](https://learn.chatgpt.com/docs/codex/cli). Once installed, start the CLI and sign in: ```bash codex ``` On first launch you choose how to authenticate: **sign in with ChatGPT** (Codex is included with Plus, Pro, Business, Edu, and Enterprise plans), or export an API key before launching: ```bash export OPENAI_API_KEY= ``` {% hint style="warning" %} **Name MCP servers with a `datasentinel-` prefix.** Every Datasentinel MCP server you register must be named starting with `datasentinel-`, for example `datasentinel-production` or `datasentinel-staging`. The Skill discovers Datasentinel servers by this prefix, so a server named otherwise will not be picked up. Use a distinct suffix per platform when you operate more than one (`datasentinel-prod`, `datasentinel-eu`, and so on). {% endhint %} ## Set it up {% stepper %} {% step %} #### Add the Datasentinel MCP server Register the server with its HTTPS URL: ```bash codex mcp add datasentinel-production --url https:///mcp ``` Codex treats any server that has a `url` as a remote streamable-HTTP server, so there is no separate transport flag to set. For more on connecting Codex to MCP servers, see the [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=app). You can also edit the configuration file directly. Servers live in `~/.codex/config.toml`, each under an `[mcp_servers.]` table: ```toml [mcp_servers.datasentinel-production] url = "https:///mcp" ``` {% hint style="info" %} **Sign in on first use.** The Datasentinel MCP server is protected by OAuth 2.1. Nothing else goes in the configuration: no token, no header. The sign-in is the next step. See [How authentication works](/manual/ai-connector/server-setup/how-authentication-works.md). {% endhint %} **Self-signed or invalid certificate** Codex validates the `/mcp` certificate against the host's system trust store and offers no switch to turn validation off. Using a valid TLS certificate is **highly recommended**: provision one from a public authority, or from an internal CA installed in the system trust store, so validation stays on. The sign-in below also opens the login page in your browser, so the browser must trust the certificate too. For details, see [MCP Server Setup](/manual/ai-connector/server-setup/mcp-server-setup.md) and the [Codex CLI configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference). {% endstep %} {% step %} #### Sign in to the platform **With a browser** Start the sign-in for the server you registered: ```bash codex mcp login datasentinel-production ``` Codex prints the link and opens the Datasentinel login page in your browser. Sign in with your **platform login and password**, the same ones as the Datasentinel web interface. The page names the assistant that is asking; after the sign-in the browser hands the session back to Codex, which confirms with `Successfully logged in`. Inside an interactive session, `/mcp` shows the server's authentication state and offers the same sign-in. You sign in once. Codex stores the session in the OS keyring, or in a file under `~/.codex/` when the host has no keyring, and renews it by itself. It asks again only after ten days without using the server, or when an administrator ends the session. Your password goes to the login page only; Codex never sees it and never asks for a token. `codex mcp logout datasentinel-production` ends the session on this host. Codex 0.157 added an `--oauth-client-registration` option (`auto`, `cimd` or `dcr`). Keep the default, `auto`: Codex then uses dynamic client registration, which is what the Datasentinel server offers. **Without a browser** On a server without a browser (an SSH session, a build machine), the sign-in still runs in the browser of your laptop, through an SSH port forward. Codex picks a random callback port unless you fix one, so first set the port in `~/.codex/config.toml` on the server. The key is a top-level one: put it above the first `[mcp_servers...]` header, or it would be read as part of that table. ```toml mcp_oauth_callback_port = 19876 [mcp_servers.datasentinel-production] url = "https:///mcp" ``` To fix the port for this server only, use `callback_port = 19876` under a `[mcp_servers.datasentinel-production.oauth]` table instead. Then open the SSH session from your laptop with that port forwarded, and start the sign-in inside that session: ```bash # on the laptop: the tunnel only exists in a session opened this way ssh -L 19876:localhost:19876 @ ``` ```bash # on the server, in that session codex mcp login datasentinel-production ``` Codex prints the authorization link (and fails to open a browser, which is expected). Open the link in the laptop's browser and sign in; the way back to `localhost:19876` travels through the tunnel to Codex on the server, which confirms with `Successfully logged in`. If you are already connected without the option, log out and reconnect with it before running the login. This procedure was verified with Codex 0.155.0. The general procedure is in [How authentication works](/manual/ai-connector/server-setup/how-authentication-works.md#sign-in-from-a-server-without-a-browser). {% hint style="info" %} **Simpler: paste the link back.** From Codex 0.157, `codex mcp login` has a `--no-browser` option. It prints the authorization link and waits for the callback address, with no port forward: ```bash codex mcp login datasentinel-production --no-browser ``` Open the link in any browser and sign in. The browser then fails to load a `http://localhost:…` address: copy that full address from the address bar, and paste it into the terminal. Check with `codex mcp login --help` that your build lists the option. {% endhint %} **For a script or a scheduled run** Where nobody can sign in, register the server with a user token as an authorization header instead. The token is the platform's 24-hour [user token](https://app.gitbook.com/o/DaDQkGCM7r2TghFSBFLQ/s/yE16Xb3IemPxJWydtPOj/implementation/platform-usage/api-reference/access-token). Codex reads it from an environment variable, so the token is never written in the configuration: ```bash export DS_TOKEN= codex mcp add datasentinel-production --url https:///mcp --bearer-token-env-var DS_TOKEN ``` The resulting entry in `~/.codex/config.toml` sends `Authorization: Bearer ` on every call: ```toml [mcp_servers.datasentinel-production] url = "https:///mcp" bearer_token_env_var = "DS_TOKEN" ``` A server registered this way never opens the login page; when the token expires, the calls fail until a fresh one is set. See [Refresh the user token automatically](/manual/ai-connector/developers/refresh-user-token.md) to keep it current. {% endstep %} {% step %} #### Install the Datasentinel Skill The Datasentinel Skill is made of several files (a `SKILL.md` entrypoint plus supporting files) and ships as a single archive, `datasentinel-skill.zip`. Download it from . Skills in Codex are file-based: there is no install command. Create the Skills directory if it does not exist yet, then unzip the archive into it so it produces a `datasentinel/` folder, and Codex discovers it on the next session. {% tabs %} {% tab title="Personal (all your projects)" %} ```bash mkdir -p ~/.agents/skills/ unzip datasentinel-skill.zip -d ~/.agents/skills/ ``` {% endtab %} {% tab title="Project (shared via Git)" %} ```bash mkdir -p .agents/skills/ unzip datasentinel-skill.zip -d .agents/skills/ ``` {% endtab %} {% endtabs %} You should end up with `~/.agents/skills/datasentinel/SKILL.md` (or `.agents/skills/datasentinel/SKILL.md`) alongside the Skill's supporting files. Each Skill lives in its own directory whose `SKILL.md` is the entrypoint. Its frontmatter carries the `description` the assistant uses to decide when to apply the Skill: ```markdown --- name: datasentinel description: How to query Datasentinel metrics through the datasentinel-* MCP servers. --- ``` {% hint style="info" %} **`.agents/skills`, not `.codex/skills`.** Codex discovers Skills under the vendor-neutral `.agents/` directory (`$HOME/.agents/skills` and each `.agents/skills` from your working directory up to the repo root), because `SKILL.md` is a cross-agent standard the same folder can serve to other assistants. The `.codex/` directory is reserved for Codex's own configuration (`~/.codex/config.toml`) and is **not** scanned for Skills. See Codex's [Build Skills](https://learn.chatgpt.com/docs/build-skills) reference. {% endhint %} {% endstep %} {% step %} #### Check your configuration List the configured servers from the terminal: ```bash codex mcp list ``` Inside an interactive `codex` session, the `/mcp` command shows the active MCP servers: ``` /mcp ``` A healthy server appears with its tools available. A server you have not signed in to yet is shown as needing authentication: go back to the sign-in step. If a server shows an error, check the URL in `config.toml` and that the server is up. **Approve the Datasentinel tools** The first time the assistant calls a Datasentinel tool, Codex asks you to approve it, once or for the rest of the session. The prompt has no permanent choice: to stop the prompts for good, set the approval mode of the server in `~/.codex/config.toml`: ```toml [mcp_servers.datasentinel-production] url = "https:///mcp" default_tools_approval_mode = "approve" ``` The modes are `approve` (never ask), `prompt` and `writes` (both ask for tools not marked read-only, which is every Datasentinel tool today), and `auto`. See the [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). A single tool can differ from the server, under `[mcp_servers.datasentinel-production.tools.]` with `approval_mode`. The Datasentinel tools only read monitoring data, so approving the whole server is safe. `approval_policy = "never"` in the same file removes every approval prompt of every kind, including shell commands and file edits; use it with care. The fields are in the [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). {% endstep %} {% endstepper %} Once the server is connected and the Skill is in place, run through the checks below to confirm the end-to-end flow. ## How the Skill loads The Datasentinel Skill loads on demand. Codex reads every Skill's name and `description` up front, and applies the full instructions automatically when your prompt relates to Datasentinel: asking about PostgreSQL performance, instances, sessions, or the platform itself is enough. One Skill serves every platform, because it discovers all the `datasentinel-*` MCP servers you registered, so adding a second platform needs no Skill change. If Codex answers generically instead (no Datasentinel tool calls in the response), load the Skill manually: * Type `$` in the composer and pick `datasentinel` to mention the Skill explicitly in your request. * Or run `/skills` to browse the discovered Skills and invoke it from there. * Or name it in the prompt: `Use the datasentinel skill to check the platform status.` If the Skill does not appear under `/skills`, re-check the unzip location from the setup step and start a new session. See OpenAI's [Build Skills](https://learn.chatgpt.com/docs/build-skills) reference for the invocation details. ## Test the MCP server and Skill Run these checks inside an interactive `codex` session. You exercise the Skill by asking in plain language and letting it drive the MCP tools (see [How the Skill loads](#how-the-skill-loads) above). The Datasentinel Skill recognises four built-in checks. Run them in order: | Ask Codex for… | What it does | | ------------------------ | ------------------------------------------------------------------------------------- | | `datasentinel help` | Displays the Skill's help, listing the available commands. | | `datasentinel platforms` | Lists every MCP server (platform) the Skill discovered by its `datasentinel-` prefix. | | `datasentinel status` | Checks the platform status, confirming the MCP server answers. | | `datasentinel whoami` | Shows who you are signed in as, your privilege and the session expiry. | These four are the setup checks. The full command list, with what each one needs, is in the [Skill commands reference](/manual/ai-connector/use-the-assistant/skill-commands.md). Start with `datasentinel help` to confirm the Skill responds. Then run `datasentinel platforms` to verify your server is discovered: each `datasentinel-*` MCP server you registered should appear in the list. Then run `datasentinel status` to confirm the platform is reachable and the MCP tools return live data. Finally, `datasentinel whoami` confirms the session belongs to your platform user, with the privilege you expect. {% hint style="success" %} If `datasentinel status` reports a healthy platform, the MCP server and the Skill are wired together correctly. You can now ask the assistant questions about your instances in plain language. {% endhint %} {% hint style="info" %} **Server not discovered? Ask the assistant to find the root cause.** If `datasentinel platforms` lists nothing, or your server is missing from it, ask Codex to debug the setup rather than hunting by hand. It can run `codex mcp list`, read the `[mcp_servers.]` tables in `~/.codex/config.toml`, and probe the endpoint itself, so it usually pinpoints the cause in one pass. Ask it something like: ``` The datasentinel-production MCP server is not discovered. Investigate and find the root cause: check my MCP configuration, the connection status of the server, and whether the /mcp endpoint answers. ``` Typical causes it surfaces: a server name that misses the `datasentinel-` prefix, a typo in the URL, a disabled server, a server you have not signed in to, an untrusted TLS certificate, or a platform that is down. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.datasentinel.io/manual/ai-connector/connect-a-cli-assistant/configure-codex-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.