Connect Codex

Prerequisites

The standard configuration has no prerequisites. Codex uses OAuth for remote MCP servers, so it signs you in. It does not read a token from a file. You need an API token only for the headless configuration at the end of this page.

Install the plugin

The Orcha plugin is the fastest method. The plugin contains the MCP server and the usage guides below as skills. It also contains a setup skill that runs after installation.

1. Run codex.
2. Run /plugins.
3. Search for Orcha.
4. Install the plugin.

If the directory does not show the plugin, add the Orcha public repository as a marketplace. Then install the plugin from that marketplace:

codex plugin marketplace add westonhancock/orcha-mcp

At installation, Codex opens the Orcha sign-in. Select the workspace and the permissions as the next section shows. After installation, go to Verify.

The remainder of this page shows the manual configuration. It gives the same connection, but without the skills in the plugin.

Add the server manually

Codex configures MCP in TOML, not in JSON. To connect in all projects, edit ~/.codex/config.toml. To connect in one trusted project only, edit .codex/config.toml in that project.

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

1. Restart Codex.
2. At first use, sign in on the page that Codex opens.
3. Select the workspace for the connection.
4. Select the permissions for the connection: read, write, and delete.

Your workspace role at consent time sets the maximum permissions. Orcha checks the permissions again on each request. If you lose a role, the connection loses those permissions immediately.

auth = "oauth" is the default, so you can remove it. This page shows it because it is the line that you change for the headless configuration.

Install the usage guides

Orcha supplies four Agent Skills. They tell an agent these things:

• Which tool answers each type of question.
• How to adjust a search that returns too few results.
• How to cite and date results.
• What an empty result means.

Codex reads skills from .agents/skills/ in your repository. It scans each parent directory up to the repository root. Codex also reads skills from ~/.agents/skills/ for all projects.

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

Codex loads a skill when a task matches its description. You can also call a skill directly, for example $retrieval.

This step is optional. The get_usage_guide tool gives the same content without installation. When the files are not present, Codex uses that tool. When you install the files, Codex uses one less tool call. Codex also has the guidance before it decides what to do.

Verify

1. In Codex, run /mcp.
2. Make sure that the orcha server is connected.
3. Make sure that the list shows its tools.

To quickly check that the plugin or the manual configuration works, tell Codex to "read the Orcha retrieval usage guide".

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

If a browser sign-in is not possible, use an API token from the API Tokens page instead of OAuth. Put the token in an environment variable. Then write the name of that variable in the configuration:

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

Give the token only the workspace and permissions that the job needs. Refer to Tokens and scoping.