Skip to content
ProjectBrain Docs
Work in progress: these docs are being written and change often.

Connect Codex

Step-by-step setup for the OpenAI Codex command-line tool.

GAOwnerExecutiveTeam leadIndividual contributorLast updated 5 October 2026

Connect Codex, OpenAI’s command-line coding tool, so it can read tasks, submit plans and link its work to them. Codex writes as the Codex bot, on your behalf.

On the ProjectBrain side

Section titled “On the ProjectBrain side”
  1. Go to Settings > MCP Connections.
  2. Find the card for the assistant and choose Connect. A dialog opens with setup steps and the MCP URL for your organization.
  3. Choose Copy next to the MCP URL. You need it in the next steps.

In your terminal

Section titled “In your terminal”

  1. Add the server with the command shown in the Connect dialog:

    codex mcp add projectbrain --url <MCP URL>

  2. Sign in:

    codex mcp login projectbrain

    A browser opens. Sign in to ProjectBrain and choose Allow.

  3. Inside codex, type /mcp to see projectbrain and its tools.

If you prefer editing config, the dialog’s Config File tab shows what to add to ~/.codex/config.toml. Then run the sign-in command.

To remove it: codex mcp remove projectbrain, then revoke the connection in ProjectBrain.

What you should see

Section titled “What you should see”

Reload Settings > MCP Connections. The card shows Connected, and the connection appears under Active Connections.

If it did not work

Section titled “If it did not work”
  • No browser window opened: sign in again from the assistant, as in the steps above.
  • The card still does not show Connected: your admin may have limited which assistants or people can connect, or a new kind of client may be waiting for approval. Ask them to check Settings > MCP Policy.
  • The assistant says a tool is missing: the connection may not have that scope. See Connect an AI assistant.

What to try first

Section titled “What to try first”

Say “ProjectBrain” in your request so the assistant uses this connection. For example:

  • What ProjectBrain tasks are assigned to me? Sort them by due date.
  • Search ProjectBrain for tasks about the login page.
  • Which ProjectBrain tasks are blocked, and what blocks them?
  • Show my ProjectBrain timesheet for this week and log 3 hours on the website project for today.
  • What should I do today in ProjectBrain? Then catch me up on what changed since yesterday.
  • Open ProjectBrain task 1234. Read it, write a plan, and submit the plan.