Codex

Codex is OpenAI’s coding agent. It comes as the Codex app (part of the ChatGPT desktop app), the codex CLI, and an IDE extension. ChatGPT and Codex share one plugin directory, so the Orbismo plugin you may already use in ChatGPT is available in Codex too. Codex also takes plain remote MCP servers, which gives you the connector and the single-world API key methods.

The Orbismo plugin

The plugin is the quickest route in the Codex app and CLI. It uses Orbismo sign-in, so it is the connector method under the hood: one install, all the worlds you grant.

Codex app: open the Plugins tab, find Orbismo, open its details and select the + button to install. Connect to Orbismo when prompted, sign in, and choose the worlds Codex may access.
Codex CLI: run /plugins inside a session to open the plugin browser, find Orbismo, and install it. Finish the sign-in in your browser.
IDE extension: plugins are not available there. Add Orbismo as an MCP server instead (below).

Start a new chat after installing. Ask Codex to list your worlds and tell it which one to work in.

The connector as an MCP server

Use this when you prefer to manage Orbismo like any other MCP server, or in the IDE extension.

Codex CLI

codex mcp add orbismo --url https://app.orbismo.com/api/v1/mcp
codex mcp login orbismo

The second command opens your browser to sign in to Orbismo and choose which worlds this connection may access. Codex stores and refreshes the tokens for you.

Codex app or IDE extension

Open Settings, then MCP servers, then Add server. Enter a name, choose Streamable HTTP, enter https://app.orbismo.com/api/v1/mcp, and save. Select Restart (in the IDE extension, Restart extension) so Codex loads the server, then select Authenticate when it appears to sign in to Orbismo and choose your worlds.

Either way the server lands in ~/.codex/config.toml:

[mcp_servers.orbismo]
url = "https://app.orbismo.com/api/v1/mcp"

See The connector for choosing a world and managing access.

A single world with an API key

To pin Codex to one world, point it at the world’s URL and give it an API key through an environment variable:

export ORBISMO_API_KEY="oc_live_<your_key>"
codex mcp add orbismo-world --url https://app.orbismo.com/api/v1/worlds/<world_id>/mcp \
  --bearer-token-env-var ORBISMO_API_KEY

Replace <world_id> with your world’s UUID (the one in the portal URL when you’re inside the world). The server gets its own name so it can sit beside the connector. Codex reads the key from the variable each time it starts, so set it in your shell profile. Use a read-only key first so the agent can’t make changes while you test.

The same thing in ~/.codex/config.toml:

[mcp_servers.orbismo-world]
url = "https://app.orbismo.com/api/v1/worlds/<world_id>/mcp"
bearer_token_env_var = "ORBISMO_API_KEY"

Manage servers

codex mcp list             # show configured servers
codex mcp get orbismo      # details for one server
codex mcp logout orbismo   # drop the stored sign-in
codex mcp remove orbismo   # remove it

Verify

In a session, ask “What MCP tools do you have?” You should see Orbismo’s tools, including list_my_worlds on the connector or the plugin. On a single-world URL, a missing tool usually means your access level doesn’t include it. On the connector the tool list is the same for every world. On a read-write connection, write tools stay listed even on worlds where you are a viewer, and the change is refused when the agent tries it. See Troubleshooting.