Setting up the Hevo MCP Server in Codex

Last updated on Nov 18, 2026

You can use the Hevo MCP server in the Codex CLI and in the Codex app. In both, the Hevo plugin installs the server and the hevo-pipelines skill in one step. When Codex starts a session, the plugin starts the server on your machine, and your requests go from your machine directly to Hevo. The plugin runs the hevo-mcp package from PyPI, so Codex needs access to pypi.org and raw.githubusercontent.com when it starts the server.

The Codex CLI and the Codex app share their settings, so you install the plugin once with the Codex CLI, and it is available in both. The plugin, the key file, and the scope that you set work the same way in both.


Requirements

You need the following to set up the server in the Codex CLI or the Codex app:

  • API credentials: Your Access Key and Secret Key, saved in the ~/.hevo/hevo-key.json key file. The server reads your API credentials only from this file, and never shows them to the agent.

  • uv: The uv tool, which runs the server and downloads the version of Python that the server needs.

  • Python 3.12: Python 3.12 installed on your machine.

  • The Codex CLI: The Codex CLI adds the Hevo plugin marketplace and installs the plugin, even if you use only the Codex app.


Differences between the Codex CLI and the Codex App

The following table lists how you work with the server in the Codex CLI and in the Codex app:

Task Codex CLI Codex app
Set up the server Install the Hevo plugin with the Codex CLI, which adds the server and the hevo-pipelines skill. Install the Hevo plugin with the Codex CLI, which adds the server and the hevo-pipelines skill.
Start using the server after you set it up or update it Exit Codex, and start a new Codex session. Quit the Codex app, and open it again.
Allow the agent to make changes Add export HEVO_MCP_DEFAULT_SCOPE=write (or delete) to your shell profile file, such as ~/.zshrc, or on Windows, run setx HEVO_MCP_DEFAULT_SCOPE write in PowerShell. Then, start a new Codex session from a new terminal. Add export HEVO_MCP_DEFAULT_SCOPE=write (or delete) to your shell profile file, such as ~/.zshrc, or on Windows, run setx HEVO_MCP_DEFAULT_SCOPE write in PowerShell. Then, quit the Codex app, and open it again.
Use the hevo-pipelines skill Codex uses the skill when you ask about Hevo. To run it yourself, use $hevo-pipelines. Codex uses the skill when you ask about Hevo. To run it yourself, use $hevo-pipelines.
Approve a change Answer the approval prompt that the server shows. Answer the approval prompt that the server shows.

Read Allowing and Approving Changes by your Agent for more information about scopes and approval prompts.


Setup Steps

Refer to the following pages for the steps to set up the server in the Codex CLI or the Codex app:


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Nov-18-2026 2.54 New document.

Tell us what went wrong