Self-hosted OpenAI Codex plugin marketplace for GEOly, the GEO (Generative Engine Optimization) platform that tracks how brands are mentioned and cited across AI engines (ChatGPT, Gemini, Perplexity, Grok, Google AI).
This repo packages the GEOly MCP server + the geoly-mcp skill into one installable Codex plugin. It is a self-hosted marketplace — it is not OpenAI's official Plugin Directory (self-serve publishing to that directory is "coming soon" per OpenAI; until then this repo is the distribution channel).
Intended home: a public repo
geoly-ai/codex-plugins. The plugin connects to the hosted GEOly MCP endpoint, so users need a GEOly account; OAuth runs at install time.
# 1) Register this marketplace (public repo → owner/repo shorthand works without credentials)
codex plugin marketplace add geoly-ai/codex-plugins
# 2) (optional) confirm it registered
codex plugin marketplace list
# 3) Install the plugin (the install verb is `add`, not `install`).
# @geoly is the marketplace slug, used to disambiguate same-named plugins.
codex plugin add geoly-mcp@geoly
# 4) On install (policy.authentication = ON_INSTALL) Codex opens the GEOly OAuth
# browser flow — sign in / authorize, and the geoly MCP tools become available.
codex plugin listInside a Codex session you can use the slash-command equivalents:
/plugin marketplace add geoly-ai/codex-plugins
/plugin install geoly-mcp@geoly
codex plugin marketplace add geoly-ai/codex-plugins --ref v0.1.0 # branch or tag
# session slash form: /plugin marketplace add geoly-ai/codex-plugins#v0.1.0Plugins do not auto-update, and marketplace upgrade alone is not enough — it refreshes the
catalog but not your already-installed copy. Getting a new version takes three steps:
codex plugin marketplace upgrade geoly # 1. pull newer commits from this repo (refresh the catalog)
codex plugin add geoly-mcp@geoly # 2. REQUIRED: reinstall to copy the updated plugin into the cache
# 3. Fully quit and relaunch Codex / start a new session — MCP tools + skill load at process start
codex plugin remove geoly-mcp # uninstall the plugin
codex plugin marketplace remove geoly # unregister this marketplace
# Underlying OAuth primitives (the install flow usually drives these for you):
codex mcp login geoly # manually run the OAuth login
codex mcp logout geoly # clear stored OAuth credentials
codex mcp list # list configured MCP serversAuto-authorize (v0.1.4+): the bundled skill now detects when the GEOly tools aren't mounted and runs
codex mcp login geolyfor you to open the OAuth window — you no longer have to find the Authenticate / 进行身份验证 button under Settings → MCP servers. After you sign in, fully restart Codex and start a new session to mount the tools. (On Codex Desktop, if the tools still don't appear after a restart, use the Codex CLI — it mounts OAuth MCP tools reliably.)
geoly-mcp exposes up to ~61 MCP tools (the exact set depends on your plan, org membership, and write profile), covering:
- Your brand (authenticated):
get_brand_overview,query_analytics,get_prompt_list/get_prompt_detail/get_prompt_citations/get_prompt_mention_rates,get_citation_overview,get_competitor_overview,get_platform_matrix,get_topic_analytics,get_audit_list, … - Public / industry intelligence (Grow+ plan):
search_public_entities,get_public_category,get_category_whitespace,get_category_brand_momentum,get_public_brand_perception,compare_public_brands,get_topic_competition_difficulty, … - Write actions (require an interactive
standard/adminprofile):create_prompt,create_topic,create_competitor,trigger_prompt(consumes credits).
The bundled skill (SKILL.md + references/) teaches Codex to pick the right tool, follow the org/brand discovery flow, and quote the correct KPI caliber (citation rate, mention rate, AIGVR, Share of Model).
- GEOly account required. After OAuth you need an active subscription; public/industry tools require a Grow+ plan. Free/basic users can authenticate but some tools return
402or are hidden. - Single-org context recommended. A user-level token spanning ≥2 orgs enters
multi-orgmode, which is read-only and disables the public/industry tool set. Pass a single org if you need those tools. - Hosted, no local server. The plugin points at
https://app.geoly.ai/api/mcp(streamable HTTP + OAuth); nothing runs on your machine.
This is a standalone repo. Clone it as a sibling of the geoly-ai/geoly-app repo:
git clone https://github.com/geoly-ai/codex-plugins.git ../geoly-codex-pluginsThe skill content under plugins/geoly-mcp/skills/geoly-mcp/ is a copy of the canonical source geoly-mcp/ in the geoly-ai/geoly-app repo. Do not hand-edit it here — edit the source and re-sync:
# from the geoly-app repo root (defaults to ../geoly-codex-plugins)
node scripts/build-codex-plugin.mjs
# or pass an explicit path / set CODEX_PLUGIN_REPO
node scripts/build-codex-plugin.mjs /path/to/geoly-codex-pluginsThat script mirrors geoly-app/geoly-mcp/{SKILL.md,CHANGELOG.md,references/**} into this plugin and reports any drift. Then git commit && git push here.
Bump plugins/geoly-mcp/.codex-plugin/plugin.json version (semver) on each release and tag the repo so users can --ref pin.
Before announcing, run the on-device checklist in geoly-app/docs/mcp/CODEX_PLUGIN_DISTRIBUTION.md (OAuth auto-trigger on install, oauth_resource value, dependencies.tools recognition, public-tool gating).
codex-plugins/
├── .agents/plugins/marketplace.json # marketplace catalog (fixed path)
└── plugins/geoly-mcp/
├── .codex-plugin/plugin.json # plugin manifest (fixed subdir; interface = plugin metadata)
├── .mcp.json # remote MCP server (OAuth)
├── assets/ # icons / logos
└── skills/geoly-mcp/ # ← synced copy of geoly-app/geoly-mcp/
├── SKILL.md
├── CHANGELOG.md
├── agents/openai.yaml # skill-level adapter: metadata + policy + MCP dependency
└── references/
GEOly · AI brand visibility (GEO) · www.geoly.ai