@joggai/mcp-client

Install the JoggAI MCP Streamable HTTP server in supported AI clients without copying API keys or storing OAuth tokens in this npm package.

Quick start

npx -y @joggai/mcp-client install codex
npx -y @joggai/mcp-client install claude
npx -y @joggai/mcp-client install cursor
npx -y @joggai/mcp-client install chatgpt

install codex automatically locates Codex in PATH, the current user's npm prefix, and standard user installation directories. On Windows it also checks the current user's roaming npm directory. npm-installed Codex runs through its official JavaScript entrypoint using the current Node executable, even when the codex.cmd shim is missing or cannot launch.

If no CLI is available, install codex downloads the official @openai/[email protected] package into a private user cache and uses it for MCP setup. This requires npm registry access on the first run, but no global installation or administrator privileges. Later commands reuse the cache. status, login, and uninstall never initiate a download. Other Windows accounts' installations and credentials are not searched; run setup under the same account used for Codex.

The cache is %LOCALAPPDATA%\JoggAI\mcp-client\codex\0.153.4 on Windows, or $XDG_CACHE_HOME/jogg-mcp/codex/0.153.4 on macOS/Linux (defaulting to ~/.cache/jogg-mcp/codex/0.153.4). OAuth credentials and MCP configuration remain in Codex's normal configuration location, including CODEX_HOME when set. An invalid JOGG_CODEX_BIN is reported explicitly; clear it to enable automatic discovery and preparation.

The default production MCP endpoint is https://api-services-intl.jogg.ai/mcp. Use --url only for an explicit test or private deployment. Entries created with the former default https://api.jogg.ai/mcp are migrated automatically; custom URLs still require --replace.

For a new or replaced Codex registration, codex mcp add starts the native OAuth flow itself. An unchanged Codex registration uses codex mcp login, so either path opens authorization exactly once. Claude Code uses its native OAuth login command. Cursor configuration is updated atomically, then Cursor completes OAuth when the user enables JoggAI in Customize > MCP. ChatGPT has no local CLI or configuration file, so the command returns explicit connector setup metadata and does not claim automatic installation.

| Client | Registration | OAuth | | --- | --- | --- | | Codex | Native CLI | Native browser login | | Claude Code | Native CLI | Native browser login | | Cursor | Atomic ~/.cursor/mcp.json update | Cursor UI | | ChatGPT | Manual connector instructions | ChatGPT UI |

Run clients to inspect the same capabilities as machine-readable JSON. Repeated Codex or Claude Code installation is idempotent: if the exact URL is already registered, the package starts login without removing or adding the entry again. Use --replace to force a same-URL entry to be rebuilt with the selected client's current OAuth metadata.

Commands

npx -y @joggai/mcp-client clients
npx -y @joggai/mcp-client install <codex|claude|cursor|chatgpt>
npx -y @joggai/mcp-client login <codex|claude|cursor|chatgpt>
npx -y @joggai/mcp-client status <codex|claude|cursor|chatgpt>
npx -y @joggai/mcp-client uninstall <codex|claude|cursor|chatgpt>
npx -y @joggai/mcp-client recover codex
npx -y @joggai/mcp-client setup-recovery codex

claude-code is accepted as an alias for claude.

Expired OAuth authorization in Codex

install codex also installs the jogg-mcp-auth recovery skill in $CODEX_HOME/skills (default ~/.codex/skills). Existing installations can add it with setup-recovery codex, which does not start login or alter MCP entries. Start a new Codex task if the running task has not discovered the new skill.

The skill instructs the agent to recover an interrupted Jogg workflow on invalid_grant, rejected refresh tokens, or reauthenticationRequired: start native browser authorization once, await consent, verify a read-only MCP call, and resume without blindly duplicating submitted generation jobs. This is agent workflow recovery; it does not modify Codex's OAuth transport or guarantee a browser prompt while no agent is running. Other hosts retain their own OAuth UI behavior.

recover codex automatically discovers the enabled Jogg HTTP entry, including custom names such as jogg. Use --name for multiple entries, or --url to select a private deployment. It never logs out, recreates the entry, downloads Codex, reads tokens, or submits media tasks. Concurrent recoveries for the same entry share one bounded native login, including a failed/cancelled outcome. Native login has a three-minute timeout. A successful result still requires verification through the active host connection. A host that caches startup failures may need its reconnect action after login.

Increasing access-token lifetime reduces refresh frequency but cannot restore an already revoked/expired refresh token. That case requires fresh consent.

Common options:

--name NAME
--url URL
--client-id ID
--scopes scope.one,scope.two
--replace

The default install requests all currently supported JoggAI MCP scopes so the complete tool set is available after consent. Use --scopes for least-privilege installations, for example --scopes openid,account.read,quota.read,catalog.read. On a new or replaced Codex registration, Codex obtains the initial scopes from the server's protected-resource metadata because codex mcp add has no scopes option. The explicit scopes apply when an existing Codex registration is logged in again.

Claude options:

--callback-port PORT
--scope local|user|project

Cursor option:

--cursor-config /path/to/mcp.json

For installations where the client executable is not on PATH, set JOGG_CODEX_BIN or JOGG_CLAUDE_BIN to its absolute path.

On Windows, npm-installed codex.cmd and claude.cmd launchers are resolved automatically from PATH. An explicit launcher path is also supported in PowerShell, including paths containing spaces:

$env:JOGG_CODEX_BIN = "$env:APPDATA\npm\codex.cmd"
npx -y @joggai/mcp-client install codex

Set the variable to the executable path alone, without extra quotes inside the value or command-line arguments.

Windows CMD uses this syntax for an optional explicit path:

set "JOGG_CODEX_BIN=%APPDATA%\npm\codex.cmd"
npx -y @joggai/mcp-client@latest install codex

Tests

npm test --workspace @joggai/mcp-client
npm run test:codex --workspace @joggai/mcp-client

The second command downloads the real official CLI into a temporary cache and tests installation, status, and removal with an empty PATH, isolated CODEX_HOME, and a local MCP server. It requires npm registry access and does not authenticate against a real JoggAI account. Run both commands on native Windows as well as macOS/Linux to verify platform behavior.

OAuth redirects

The Jogg OAuth deployment must pre-register the client-specific redirect URLs. The defaults used by this package are:

ChatGPT:        https://chatgpt.com/connector_platform_oauth_redirect
Claude Code:    http://localhost:5555/callback
Cursor desktop: http://localhost:8787/callback
Cursor agents:  https://www.cursor.com/agents/mcp/oauth/callback

Codex uses its native loopback callback and binds tokens to the exact MCP resource URL. OAuth credentials remain in the selected client's credential store; this package never receives or persists them.