Installing the Hevo Plugin in the Codex CLI
On This Page
The Hevo plugin adds the Hevo MCP server to the Codex CLI, so you do not need to add the server to the settings of Codex yourself. Along with the server, the plugin installs the hevo-pipelines skill, which gives Codex instructions for using the tools of the server, such as the steps to find the cause of a failure and the safety rules for changes. Read Components for more information.
When Codex starts a session, the plugin starts the server on your machine, and the server reads your API credentials from a key file.
Prerequisites
-
An active Hevo account. You can start with a 14-day full-feature, free trial account.
-
You are assigned the required role for the actions that you want the agent to perform.
-
You have generated your API credentials, and downloaded or copied them. Read Generating your API Credentials for the steps.
-
uv is installed on your machine. The uv tool runs the server, and downloads the version of Python that the server needs.
-
Python 3.12 is installed on your machine.
-
The Codex CLI is installed on your machine.
Saving your API Credentials
The server looks for your API credentials in a key file named hevo-key.json, in the .hevo folder of your home directory, such as ~/.hevo on macOS and Linux, or C:\Users\<your user name>\.hevo on Windows. Save the file that you downloaded when you generated your API credentials as this key file. The file that you download from Hevo is already named hevo-key.json. Hevo shows the Secret Key only once, so if you did not download or copy it, generate a new pair of API credentials.
Perform the following steps to save your API credentials:
-
Run the following commands in a terminal to create the
.hevofolder and move the downloaded file into it ashevo-key.json:mkdir -p ~/.hevo mv "<path to the downloaded file>" ~/.hevo/hevo-key.jsonOn Windows, run the following commands in PowerShell instead:
New-Item -ItemType Directory -Force "$HOME\.hevo" | Out-Null Move-Item "<path to the downloaded file>" "$HOME\.hevo\hevo-key.json"If you copied the Access Key and Secret Key instead of downloading them, run only the command that creates the
.hevofolder. Then, create thehevo-key.jsonfile in the folder in a text editor, with the following content, and save it as plain text, without a.txtextension:{ "access_key": "<your Access Key>", "secret_key": "<your Secret Key>" } -
Run the following command to allow only you to read the file:
chmod 600 ~/.hevo/hevo-key.jsonOn Windows, run the following commands in PowerShell instead. They allow only you to access the
.hevofolder and the key file:icacls "$HOME\.hevo" /inheritance:r /grant:r "${env:USERNAME}:(OI)(CI)F" icacls "$HOME\.hevo\hevo-key.json" /inheritance:r /grant:r "${env:USERNAME}:F"On macOS and Linux, the server does not use a key file that other users on the machine can read. On Windows, the server does not check who can read the file, so these commands prevent other users from reading your API credentials.
Do not paste your API credentials into a conversation with your agent. If you paste them by mistake, generate a new pair of API credentials and delete the existing pair. Read Rotating your API Credentials for the steps.
Your API credentials are now saved in the key file, and you can install the plugin.
Installing the Plugin
The plugin is installed from the Hevo plugin marketplace, which you add to Codex once.
Perform the following steps to install the plugin:
-
Run the following commands in a terminal to add the Hevo plugin marketplace and install the plugin:
codex plugin marketplace add hevoio/hevo-mcp codex plugin add hevo-data@hevo-dataAlternatively, run the
/pluginscommand in Codex, and select the hevo-data plugin from the hevo-data marketplace. -
Start a new Codex session. If Codex is running, exit it first.
To check that the plugin is installed, run the codex plugin list command in a terminal. The list shows hevo-data@hevo-data as installed.
Codex uses the hevo-pipelines skill when you ask about Hevo. To run the skill yourself, use $hevo-pipelines. When the agent calls a Hevo tool, Codex can ask for your permission to run it, depending on its approval setting. This permission is separate from the approval prompts of the server.
After you install the plugin, Codex can connect to Hevo.
Verifying the Connection
The agent needs your account region, which is the subdomain in the URL of your Hevo account, such as us in us.hevodata.com. If you do not name the region in your request, the agent asks you for it, and then names it in every request to Hevo. Read Identifying your Region to find your account region.
Note: The eu2 region has only Edge Pipelines, and the us-gcp region has only Standard Pipelines. In these regions, the agent can work only with the type of Pipeline that is available in the region.
Ask Codex to run hevo_whoami for region us, replacing us with your account region. The agent calls the hevo_whoami tool and reports the following details:
-
The region of the check.
-
The key file from which the server read your API credentials.
-
The result of checking your API credentials with the Hevo API for Edge Pipelines, Standard Pipelines, and team users. In the
eu2andus-gcpregions, the check reports the type of Pipeline that is not available in the region as not offered. If the role of the user who generated your API credentials does not allow an action, the check for that action fails, such as the check for team users. -
The changes that the agent is allowed to make.
-
The folder from which the server reads your secret files.
-
The version of the server, and whether a newer version is available.
-
The result of checking the installed components against the versions with which the release was tested.
-
The fingerprint of the tools that the server provides.
If the check fails, the agent reports the reason. Do the following based on the reason:
-
The server cannot find your API credentials: Check that your key file is named
hevo-key.jsonand is in the.hevofolder of your home directory. -
The key file does not contain an Access Key and a Secret Key: Save the file that you downloaded from Hevo without changes, or create the file with the content in the Saving your API Credentials section.
-
Hevo rejects your API credentials: Check that the Access Key and the Secret Key are correct and not deleted. For teams created before Release 2.00, API credentials work only in the region in which you generated them, so check that you specified that region.
-
The server does not use your key file because other users can read it: Run the
chmod 600command in the Saving your API Credentials section. -
The server does not use your key file because it is a symbolic link: Delete the link from the
.hevofolder, and move or copy the key file itself into the folder. A symbolic link is a shortcut that points to a file in another folder.
If Codex does not list any Hevo tools, check that uv is installed and that the uvx command runs in a new terminal. Then, exit Codex, and start it again from a new terminal.
When the check succeeds, the agent can view your Hevo account, but cannot change anything until you allow changes. Read Allowing and Approving Changes by your Agent to allow the agent to make changes.
Updating the Plugin
The hevo_whoami tool reports when a newer version of the server is available. Run the following command in a terminal to update the plugin:
codex plugin marketplace upgrade hevo-data
After you run this command, exit Codex, and start a new Codex session. The agent then uses the new version of the server.
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. |