Integrate the MCP Server with OpenAI Codex

On-Premise

You can now connect OpenAI Codex by adding the MCP server details to your Codex configuration file. Codex stores MCP server settings in config.toml. This file is usually located at ~/.codex/config.toml, and in the IDE extension you can open it from the MCP settings menu.

Before integrating the MCP Server with OpenAI Codex, review the Security considerations and Privacy and regulatory sections. The MCP allows external AI systems to access analytics data from your Matomo instance. You must ensure that appropriate authentication, data access controls, and privacy safeguards are in place before allowing an AI tool to query your analytics data.

Before you start

Ensure the Matomo MCP server is enabled. For Matomo On-Premise, install and activate the MCP plugin before use.

Configure Codex

Make sure you have access to Codex or your OpenAI account, your Matomo MCP endpoint URL, and a Matomo API token.

  1. Open Codex > Settings > Configuration.
  2. Click Open config.toml. If the file does not exist yet, create it.
  3. Codex supports both a user-level ~/.codex/config.toml file and a project-level .codex/config.toml file.
  4. Add the following configuration and replace:
    • YOUR_MCP_URL with your Matomo MCP endpoint, and
    • YOUR_API_TOKEN with your Matomo API token or the access token obtained using OAuth 2.0.
  5. Save the file.
[mcp_servers.analytics]
url = "YOUR MCP URL"
http_headers = { "Authorization" = "Bearer $YOUR_API_TOKEN" }

Restart Codex so the new MCP configuration is loaded. After the restart, open a session and ask a question about your Matomo analytics data. If the MCP server is configured correctly, Codex should be able to access the available analytics tools through the Matomo MCP. In the Codex terminal UI, you can also use /mcp to view active MCP servers.

Using Codex CLI

The default Codex CLI configuration file is located at: ~/.codex/config.toml

  • After updating the configuration file, restart the Codex CLI so the changes take effect.
  • To temporarily disable the MCP server without removing the configuration, add the following setting to the MCP server configuration: enabled = false.
Previous FAQ: Configure the Matomo MCP Server