Connect Codex

Prerequisites

None for the standard setup. Codex uses OAuth for remote MCP servers, so it signs you in rather than reading a token from a file. You only need an API token for the headless setup at the bottom of this page.

Add the server

Codex configures MCP in TOML, not JSON. Edit ~/.codex/config.toml to connect in every project, or .codex/config.toml in a trusted project to scope it there:

[mcp_servers.orcha]
url = "https://app.tryorcha.com/mcp"
auth = "oauth"

Restart Codex. On first use it opens a sign-in, where you pick the workspace the connection runs against and choose which of read, write, and delete it gets. Permissions are capped at your workspace role at consent time and re-checked on every request, so losing a role narrows the connection right away.

auth = "oauth" is the default and can be omitted. It is written out here because it is the line you would change for the headless setup.

Install the usage guides

Orcha ships four Agent Skills that tell an agent which tool answers which kind of question, how to tune a search that came back thin, how to cite and date results, and what an empty result actually means. Codex reads skills from .agents/skills/ in your repository, scanning upward to the repository root, or from ~/.agents/skills/ for every project.

~/.agents/skills/
├── retrieval/
│   ├── SKILL.md
│   └── references/
├── citations/
│   └── SKILL.md
├── authoring/
│   └── SKILL.md
└── troubleshooting/
    └── SKILL.md

Codex loads one when a task matches its description, and you can call one directly with $retrieval.

This step is optional. The same content is available through the get_usage_guide tool with no installation, which is what Codex falls back on when the files are not present. Installing them saves a tool call and makes the guidance available before Codex decides what to do.

Verify

Run /mcp inside Codex to confirm the orcha server is connected and its tools are listed. Asking Codex to "read the Orcha retrieval usage guide" is a quick check that either path is working.

Usage

• "Search my Orcha workspace for our deployment requirements"
• "Check which Orcha memories apply to this task and use the best match"
• "Grep my Orcha workspace for anything mentioning ORCHA_TOKEN"

Headless and CI

Where a browser sign-in is not possible, use an API token from the Tokens page instead of OAuth. Put the token in an environment variable and name that variable in the config:

[mcp_servers.orcha]
url = "https://app.tryorcha.com/mcp"
bearer_token_env_var = "ORCHA_TOKEN"

Scope the token to the workspace and permissions the job actually needs. See Tokens and scoping.