Skip to content

Updated

OpenAI Codex

OpenAI Codex CLI reads MCP server configuration from ~/.codex/config.toml. The file uses TOML format with a [mcp_servers.<name>] table for each server.

Public Agent Plugin listing pending

The portable Agent Plugin package @lyrashield/agent-plugin@0.1.31 is published; the Codex listing and authenticated runtime acceptance are still pending. Do not install from the marketplace's mutable preparation branch. Use the direct MCP fallback below until those checks pass. This plugin-oriented CLI path does not provide a direct-MCP config writer for Codex.

Authenticate local stdio

With Node.js 24 or newer, run the pinned login command in the same OS account that starts Codex and select the intended workspace. The stdio MCP server reads the local credential store; this login is separate from client discovery.

npx -y lyrashield@0.2.14 login --oauth

Configuration

Open or create ~/.codex/config.toml and merge the following block, preserving other servers. This direct-MCP fallback is a manual TOML merge; CLI config writing is offered only for exact supported client contracts. The env sub-table stores explicit values. The separate env_vars field accepts an array of names to inherit from Codex's parent process.

Manual fallback: merge the following into ~/.codex/config.toml. Recommended: run npx -y lyrashield@0.2.14 login --oauth once; the local MCP server reads the selected workspace credential from ~/.lyrashield/credentials.json. If you use an API key instead, set it in your private process environment before starting the client.

[mcp_servers.lyrashield]
command = "npx"
args = ["-y", "@lyrashield/mcp@0.2.12"]

[mcp_servers.lyrashield.env]
LYRASHIELD_API_URL = "https://app.lyrashieldai.com"
Manual setup: the pinned CLI package (lyrashield@0.2.14) has no matching installer contract for this integration. Use the configuration or client instructions above and verify the client loads it.

Important gotchas

  • Explicit values belong in `[mcp_servers.lyrashield.env]`. Codex reserves `env_vars` for an array of environment-variable names inherited from the parent process.
  • Codex remote MCP authentication uses `bearer_token_env_var` or `http_headers`; a `headers` table is not the documented field.
env_vars vs. env: use [mcp_servers.lyrashield.env] for explicit values. Use env_vars = ["NAME"] only to inherit named variables.

Confirm client discovery

Restart Codex CLI and inspect its available servers and tools. Confirm the LyraShield server is discovered before making a service call.

Verify an authenticated read

Ask Codex to call lyrashield_list_workspaces and confirm the expected workspace. A listed server alone does not prove authentication; a successful read does not prove scan or write acceptance.

Requirements: Node.js 24+ and a LyraShield workspace OAuth login. The @lyrashield/mcp package is published on npm, so npx -y @lyrashield/mcp@0.2.12 resolves directly.