Connecting Apps

Codex

Codex is OpenAI's coding agent. The Codex CLI, the IDE extension and the Codex app share one configuration, so you connect your Omeka site once. Codex then works with the collection as your Omeka user.

Before you start

  • Install Codex and sign in to it.
  • Find your site's MCP address. It is shown on Admin > MCP connections, and is your site's address followed by /mcp, for example https://archive.example.org/mcp.

Connect with your Omeka account

  1. In a terminal, add the server and sign in:

    codex mcp add omeka --url https://archive.example.org/mcp
codex mcp login omeka

  2. Your browser opens your Omeka site. Sign in if asked, review the permissions, and choose Allow. Untick Create and edit to give Codex read-only access.

  3. In Codex, type /mcp to check that omeka is connected, then ask: "Using the omeka tools, what is in this collection?"

If signing in fails, try forcing the registration method with codex mcp login omeka --oauth-client-registration dcr (or cimd).

Connect with an API key

  1. In the Omeka admin, open your user page (Admin > Users > your name > Edit) and go to the API keys tab. Create a key and copy the identity and credential; the credential is shown only once.

  2. Add the server to ~/.codex/config.toml:

    [mcp_servers.omeka]
url = "https://archive.example.org/mcp"
bearer_token_env_var = "OMEKA_MCP_TOKEN"
tool_timeout_sec = 300

  3. Set the variable, joining the identity and credential with a colon, in the shell profile that starts Codex:

    export OMEKA_MCP_TOKEN="KEY_IDENTITY:KEY_CREDENTIAL"

The IDE extension and the Codex app read the same variable, so set it where they can see it, for example in your shell profile.

Settings worth changing

All of these go under [mcp_servers.omeka] in ~/.codex/config.toml.

Setting Why
tool_timeout_sec = 300 Codex stops a tool after 60 seconds by default. Adding media from a web address downloads the file while the tool runs, which can take longer.
enabled_tools = [...] Limit Codex to some tools. Listing only omeka_info, search_vocabulary, get_resource_template, search_resources and get_resource gives a read-only setup, whatever your Omeka role allows.
default_tools_approval_mode Controls when Codex asks before calling a tool. See the Codex configuration reference for the choices.

Uploading files

To attach files from your computer, Codex asks the site for a one-time upload address and sends each file to it with curl. Codex needs permission to run commands with network access in your sandbox settings; approve the curl commands when asked. See Working with an agent.

Disconnect

  • Signed in with your account: choose Disconnect next to Codex on Admin > MCP connections.
  • Using an API key: delete the key on your user page.
  • To remove the server from Codex, delete the [mcp_servers.omeka] section from ~/.codex/config.toml.
Log in for Support