Codex plugin · OAuth MCP

Use ONE securely inside Codex

Connect to ONE without cloning the private application repository. Each person signs in with their own account, sees only permitted boards, and can retrieve the authoritative GeoTech brand standards for presentations, Complex Decisions, documents, and visual design.

Choose the connection you need

Recommended · zero local files

Direct MCP server

Adds the complete hosted ONE toolset. Codex only stores the server configuration and OAuth session; you do not download or run ONE code.

Branded experience

Full Codex plugin

Adds the same MCP tools plus the ONE plugin card, starter prompts, logo, and ONE workflow skill from a small public repository.

1. Ask an administrator for access

Open ONE and choose Admin menu.
Open the person's account and use the ONE workspace access type.
Assign a permission group, or select individual boards and BackOffice sections directly.
Choose View only or Can edit for each direct assignment.

2A. Install only the MCP server

This is the smallest installation and requires no repository checkout, Node package, Python package, or local MCP script.

Codex desktop: open Settings → MCP servers → Add server, choose Streamable HTTP, name it ONE, enter https://one.geotech.one/api/mcp, save, and authenticate.

Codex CLI:

codex mcp add one `
  --url https://one.geotech.one/api/mcp `
  --oauth-resource https://one.geotech.one/api/mcp

codex mcp login one --scopes crm.read,crm.write
codex mcp list

2B. Install the full plugin from Codex desktop

No terminal command and no repository clone are required. Codex downloads a marketplace snapshot from the small public ONE_Codex repository. The private ONE application source is not downloaded.

Repository rename

Seeing “already added from a different source”?

Codex still has the retired GeoCRM_Codex repository URL registered under the stable geotech-one marketplace name. Replace only that local source registration:

codex plugin marketplace remove geotech-one
codex plugin marketplace add Geodesic-Games/ONE_Codex --ref main
codex plugin add one@geotech-one

This does not delete ONE data, permissions, or server-side OAuth grants. If the marketplace already points to ONE_Codex, use codex plugin marketplace upgrade geotech-one instead.

Install with the Codex desktop interface

Open Plugins in Codex desktop.
Open the Create menu in the upper-right corner and select Add plugin marketplace.
For Source, enter Geodesic-Games/ONE_Codex.
For Git ref, enter main.
Leave Sparse paths empty. The repository is already small, and Codex needs its marketplace catalog and plugin folder.
Select Add marketplace.
If necessary, select the refresh icon, then open Personal and choose the ONE marketplace source.
Open ONE and select the plus or Install button. ONE's required app dependency opens the connection flow during this first installation.
Complete the ONE authorization window using the Google account registered in ONE, then choose Authorize ONE.
Confirm the blue icon appears in the Installed row, restart Codex desktop, and start a new task so the plugin skill and authenticated MCP tools load.

This registers and installs the marketplace entirely through Codex desktop. You do not need to run codex plugin marketplace add.

Optional CLI alternative

If you prefer PowerShell or need a troubleshooting fallback, these verified commands perform the same registration and installation:

codex plugin marketplace add Geodesic-Games/ONE_Codex --ref main
codex plugin add one@geotech-one
codex plugin list

Complete the browser sign-in, restart Codex desktop, and start a new task after installation. The ONE card will appear under Plugins in Codex desktop.

3. Connect your account

Installing the plugin opens the ONE authorization page. Sign in with the Google account registered in ONE and authorize the connection. Then ask: “List the ONE boards I can access.”

The connection uses OAuth authorization code flow with PKCE, short-lived access tokens, and persistent rotating refresh tokens. Codex reuses the session across app restarts and new tasks until you log out, remove the plugin, revoke the connection, or ONE disables the account. ONE re-checks account status and board permissions on every call, so an administrator can change or revoke access immediately.

Use the GeoTech brand standard

Before creating or substantially revising a presentation, Complex Decision, product or website design, UI, document, report, chart, diagram, campaign, email, social post, or other visual GeoTech work, ask Codex to call get_brand_standards. It returns the same approved logos, exact palette, Outfit and IBM Plex Sans typography, patterns, Firebase-hosted source files, digital design-system workflow, guardrails, clear-space rules, and contrast guidance shown on ONE's Branding page. Use only the returned ONE asset URLs; Branding never relies on external file links.

Treat that response as authoritative: start from approved source artwork or templates, never redraw or transform the mark, and review the result at its actual delivery size before sharing it.

Access model

View only

List boards, search items, inspect schemas, and read complete item details.

Can edit

Create and update items, add comments, preview or apply moves, and perform confirmed soft deletes.

BackOffice modules

Read Finance Overview, Flow, Accounts, Transactions, and Imports; Documents agreements and templates; Hardware inventory; and Procurement requests only when that individual module is currently granted.

Useful prompts

Get the GeoTech brand standards before designing this presentation.
List my boards and show whether each is view-only or editable.
Search Contacts for people connected to Acme.
Show the Deals board schema before creating anything.
Preview moving these Production items to Review without applying it.

Update or remove

Refresh the public plugin repository and reinstall the current package:

codex plugin marketplace upgrade geotech-one
codex plugin add one@geotech-one

Remove the plugin or the direct MCP connection:

codex plugin remove one@geotech-one

codex mcp logout one
codex mcp remove one

Troubleshooting

No boards: the signed-in account needs a permission group or direct board assignment.
Write denied: the board is view-only or the OAuth grant does not include write access.
Marketplace already added from another source: follow the repository-rename repair above to replace the retired GeoCRM_Codex source with ONE_Codex.
Marketplace missing: reopen Create → Add plugin marketplace, verify the source and main Git ref, leave Sparse paths empty, and select refresh.
Plugin missing after installation: confirm its icon is in the Installed row, restart Codex desktop, and start a new task.
No login window: refresh the geotech-one marketplace, install ONE again to load the current required app dependency, then select Connect if Codex is already showing the plugin card. Complete authorization, restart Codex desktop, and use a new task. If codex mcp list shows another local server using the same endpoint, remove or rename that legacy entry before reinstalling.
Connector says ONE Test: this label belongs to the registered ChatGPT developer connection, not the local plugin alias. Open ChatGPT Plugins and keep that connection named ONE. If the existing record cannot be renamed, create a replacement named ONE and update the plugin package to its new asdk_app_... ID.
API-key inactive error: this is the legacy local API-key connector, not the OAuth plugin. Remove or rename that older MCP entry, then reinstall ONE and restart Codex desktop.