Codex plugin · OAuth MCP

Use ONE securely inside Codex

Install ONE in Codex Desktop and authenticate with your own ONE account. A personal ChatGPT Plus or Pro account can use this flow without a Team or Enterprise workspace, terminal command, API key, or private repository checkout.

Choose the connection you need

Recommended · zero terminal setup

Full Codex plugin

Adds one credential-free remote MCP connection, the ONE plugin card, starter prompts, logo, and the shared safe-workflow skill.

Developer alternative

Direct MCP server

Adds only the hosted ONE tools. It omits the plugin card, starter prompts, and shared workflow safeguards.

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. Optional developer-only MCP setup

This advanced alternative installs only the hosted server and requires manual client configuration. Most Codex Desktop users should use the zero-terminal plugin flow in 2B.

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.

Before installation, remove or disable any manually configured user-level ONE or one MCP connection and any one-api-key, one_api_key, or one-amazon-import connection. Keep only the plugin-managed one connection so Codex does not load duplicate tools under different identities.

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.
Select Authenticate, sign into ONE with the Google account registered there, review the requested access, and 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, installs, and authenticates the marketplace entirely through Codex Desktop. You do not need to run codex plugin marketplace add or set ONE_MCP_API_KEY. The ONE account controls ONE permissions independently from the personal ChatGPT account used to access Codex.

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

After installation, select Authenticate. Codex 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

To revoke the OAuth grant without changing your personal ChatGPT account, open your signed-in ONE profile menu, choose Connected apps, and disconnect Codex.

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 authentication action: refresh the geotech-one marketplace, reinstall ONE, and select Authenticate. Complete authorization, restart Codex Desktop, and use a new task. Remove any manually configured user-level ONE or one server or key-backed alias before reinstalling.
ChatGPT web does not show ONE: this Codex Desktop package does not publish the separately registered ChatGPT app. That integration remains deferred until OpenAI approval.
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.