Connect Codex to OrgRelay

Codex reads MCP servers from config.toml. Three lines and one environment variable give it the company's documents, tables and connected systems, under your own OrgRelay permissions.

Get a personal token first, as described on the MCP overview, and replace https://ai.example.com with your company's OrgRelay address.

#Remote connection

Add to ~/.codex/config.toml:

[mcp_servers.orgrelay]
url = "https://ai.example.com/mcp"
bearer_token_env_var = "ORGRELAY_TOKEN"

Then put the token in your shell profile, for example ~/.zshrc, and open a new terminal:

export ORGRELAY_TOKEN=<your-token>

Codex sends the variable's value as Authorization: Bearer ... on each request.

#Local connection (bridge)

If your Codex version does not support remote servers, or OrgRelay is only reachable from the Mac mini, use the bridge script OrgRelay serves. It needs Node.js 18 or later.

curl -fsSL https://ai.example.com/mcp/orgrelay-mcp.mjs -o ~/orgrelay-mcp.mjs

[mcp_servers.orgrelay]
command = "node"
args = ["/Users/you/orgrelay-mcp.mjs"]
env = { ORGRELAY_URL = "https://ai.example.com/mcp", ORGRELAY_TOKEN = "<your-token>" }

#Check the connection

codex mcp list

orgrelay should be listed. Inside the Codex TUI, /mcp shows active servers and their tools.

#Project scope

Codex also reads .codex/config.toml inside a trusted project. That is useful when a repository's work needs company data, for example a service that implements a connector. Keep bearer_token_env_var in the file and the token itself in each developer's environment, never in the repository.

#AGENTS.md

Paste OrgRelay's recommended system prompt into AGENTS.md. Codex then searches before answering, cites file names, uses query_table for numbers and proposes changes only with create_approval_request. Without it, Codex tends to answer from memory and estimate figures.

#Checking permissions

Ask Codex: "Use orgrelay to list salaries in the finance folder." With an ordinary employee's token, the answer must be that nothing is accessible. Permissions are enforced on the OrgRelay server, so rephrasing, path tricks or SQL do not help. If any figures appear, revoke the token at My account → MCP connections and tell the administrator.

#Codex while building connectors

When you build a connector, Codex can call it directly before OrgRelay is involved:

[mcp_servers.sample_erp]
url = "http://127.0.0.1:8787/mcp"
bearer_token_env_var = "SAMPLE_ERP_TOKEN"

Run a template from the quickstart, point Codex at it and try the tools. The MCP transport page explains what the server must return, and the self-test tool gives a formal verdict.

#Troubleshooting

#Data location

Tool results become part of the Codex conversation and are sent to OpenAI. Departments that must keep data in-country should use OrgRelay's own app with a domestic or local model; the owner can switch MCP off per person. The policy side is described for owners on orgrelay.com/security.

#Common questions

Why an environment variable? So config.toml never contains the token.

"Does not recognise url"? Update Codex or use the bridge.

codex mcp add? Edit config.toml for bearer tokens.

#Next

• Other clients: Claude Code, Claude Desktop, Cursor.
• Company-wide rules: enterprise MCP patterns.
• Which business systems your token can reach: the connector directory.
• Why approvals stay in OrgRelay: human-in-the-loop.
• Company skills over MCP: Agent Skills.
• Vendor servers worth knowing about: official MCP servers.
• Rules every connected system follows: security requirements and approvals and write tools.
• Building a connector to test from Codex: code templates.

#Related pages

• Connector spec: manifest fields, naming, errors, paging and versioning.
• Authentication: tokens, OAuth client credentials and rotation.