---
title: "Connect Codex to HitKeep Analytics | HitKeep"
description: "Install the first-party HitKeep skills through the Codex marketplace, add a separate OAuth MCP connection, verify scoped reports, and revoke access."
canonical: "https://hitkeep.com/guides/integrations/codex/"
---

# Connect Codex to HitKeep Analytics

Use the first-party plugin for analytics instructions and a separate MCP connection for data. Codex can then investigate traffic or tracking questions using aggregate evidence from the HitKeep sites you explicitly authorize.

## Before you start

- Use a Codex version with native plugin marketplace and HTTP MCP support. The installation flow was checked with Codex CLI 0.164.0; current commands are also available through `codex plugin --help` and `codex mcp --help`.
- Sign in to the HitKeep instance that owns the sites you intend to share.
- Use a canonical HTTPS MCP endpoint that advertises OAuth support. The published skills package is independent of the 2.15.0 application rollout; [check release availability](https://hitkeep.com/guides/security/oauth/#release-availability) before using OAuth or the Assistants page on an older instance.
- Keep analytics access separate from any repository or execution permissions you give Codex. HitKeep MCP grants neither source access nor administrative writes.

## Install the first-party plugin

Add the versioned repository marketplace and install the analytics package:

```
codex plugin marketplace add HitKeep/hitkeep-assistant-plugins --ref v2.15.0
codex plugin add hitkeep-analytics@hitkeep
codex plugin list --marketplace hitkeep --json
```

Check that `hitkeep-analytics@hitkeep` is installed and enabled at version `2.15.0`. The package supplies five skills:

- `hitkeep-analytics`
- `hitkeep-traffic-diagnosis`
- `hitkeep-ai-visibility-analyst`
- `hitkeep-ecommerce-analyst`
- `hitkeep-tracking-verifier`

It contains no bundled MCP endpoint, credentials, or executable hooks. Start a fresh session if the new skills are not visible in an existing conversation. Repository marketplace installation is separate from approval in the universal ChatGPT/Codex directory.

The [first-party release](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/tag/v2.15.0) also provides the portable ZIP and checksums. Use the [ChatGPT guide](https://hitkeep.com/guides/integrations/chatgpt/) for native private archive installation in ChatGPT; do not assume a CLI install installs a cloud plugin into that account.

## Copy the endpoint from HitKeep

Open **Integration → Assistants** and copy the MCP endpoint. Use your actual EU, US, or self-hosted instance, including its custom MCP path or proxy prefix.

![HitKeep Assistants page with the canonical MCP endpoint and Codex setup link](https://hitkeep.com/_astro/mcp.DtQD81jG_Z29RaME.webp)

The displayed endpoint identifies your instance. Copying it does not verify a connected Codex session.

## Add and authorize MCP separately

Replace the example URL with your copied endpoint:

```
codex mcp add hitkeep --url https://analytics.example.com/mcp
codex mcp login hitkeep --scopes sites:read,analytics:read
```

Complete the browser flow if the add command starts it immediately; otherwise use the login command. Sign in to HitKeep and review the requesting client, MCP resource, team, scopes, and selected sites. Approve only the sites needed for the investigation.

Use the native client’s validated HTTPS Client ID Metadata Document (CIMD) by default. If an explicit native registration is necessary, ask the HitKeep operator to [pre-register an operator-controlled public client](https://hitkeep.com/guides/security/oauth/#pre-register-an-operator-controlled-client), then use its client ID with Codex’s supported setup. **Integration → OAuth clients** accepts HTTPS callbacks only; it cannot register a native HTTP loopback callback. Preserve the exact callback hostname and allow only the permitted loopback port variation. Do not add a client secret or relax callback validation. See the [OAuth guide](https://hitkeep.com/guides/security/oauth/) for client and resource binding.

For an instance without OAuth, use a [scoped API-client token](https://hitkeep.com/guides/security/api-clients/) only through a client-supported bearer-token secret store. Never put a token in a prompt, shell history, or committed configuration.

## Verify the connection with a small query

Ask Codex to list the authorized HitKeep sites. Select the intended site and try: “Summarize the last seven complete days against the previous seven. Check source changes and event coverage, and distinguish measured facts from possible causes.”

Confirm an aggregate tool response succeeded for the selected site. A plugin inventory, successful login, or endpoint copy alone is not proof that analytics queries work. The [MCP catalog](https://hitkeep.com/guides/integrations/mcp/) describes supported reports and limits; use date ranges and report sections that fit the question.

## Review and revoke access

Open the HitKeep header user menu and choose **Connected applications**. Review the grant and revoke it when it is no longer needed. Current site permissions still apply to subsequent requests.

![HitKeep Connected applications list for reviewing and revoking assistant grants](https://hitkeep.com/_astro/oauth-connected-applications.CfjT_uq-_Z1piMnC.webp)

Grant management belongs to HitKeep. Removing a local skills package is a different operation from revoking data access.

After revocation or grant expiry, run the client’s login flow again and review consent. Access-token refresh and grant lifetime are separate; see the [OAuth guide](https://hitkeep.com/guides/security/oauth/). If you remove a local client connection as part of troubleshooting, ensure its HitKeep grant is also revoked when you intend to stop data access.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Plugin commands unavailable | Check the installed Codex version and its native plugin feature availability. |
| Plugin installed but no HitKeep tools | Add MCP separately; the skills package intentionally does not configure a server. |
| OAuth discovery fails | Confirm the application version, HTTPS canonical URL, leader endpoint, and advertised metadata. |
| Callback rejected | Preserve the exact callback hostname and registered public client identity. |
| Authorized site missing or request denied | Check the consented team, sites, scopes, and current site membership; dashboard site switching does not expand a grant. |
| Reports are empty | Confirm date ranges, tracker/event collection, imported Search Console data, and crawler feeds where relevant. |

MCP excludes raw hit exports, dashboard cookies, billing, token management, and administrative writes. Authorized aggregate results are shared with the assistant you connect. See [MCP behavior](https://hitkeep.com/guides/integrations/mcp/) and [the Codex integration overview](https://hitkeep.com/use-cases/codex-web-analytics/).

[Previous ChatGPT analytics setup](https://hitkeep.com/guides/integrations/chatgpt/)[Next HitKeep Agent Skills](https://hitkeep.com/guides/integrations/hitkeep-agent-skills/)