Quick Start: Codex

From Codex you get live Amazon data in the repository you are already working in: pull real campaign or catalog data while you build, prototype an Amazon agent against it, and keep the same scoped auth in both the CLI and the IDE extension.

Connect Codex to your private MCP server so it can use your tools while working in a local repository. Codex shares MCP configuration between the CLI and IDE extension, so you only need to add the server once.

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace {your-private-mcp-host} with the private host shown in your dashboard.

Prerequisites

• Codex CLI installed and signed in.
• A connected workspace with access to your private MCP server.
• A dashboard API key from the Keys tab.
• The private MCP host assigned to your deployment.

Copy prompt

Paste this into Codex if you want it to walk you through setup:

Walk me through setting up my private MCP server in Codex, step by step.

Use the Codex CLI MCP configuration, not a local wrapper or one-off script.

Use the private host from my dashboard:
https://{your-private-mcp-host}/mcp

Use my local MCP_API_KEY environment variable. Do not ask me to paste or share the raw key in chat. If MCP_API_KEY is not set in this shell, tell me to export it from my dashboard first.

Add the server with:
codex mcp add private-mcp --url https://{your-private-mcp-host}/mcp --bearer-token-env-var MCP_API_KEY

Then verify it with:
codex mcp list

In the Codex TUI, verify the active server with:
/mcp

1. Set your local key

Set the API key in the shell that launches Codex:

export MCP_API_KEY="mcp_live_..."

For repeated use, store it in your shell profile or secret manager. Do not commit the raw value to the repository.

2. Add the MCP server

Add the remote HTTP MCP server:

codex mcp add private-mcp \
  --url https://{your-private-mcp-host}/mcp \
  --bearer-token-env-var MCP_API_KEY

Codex reads the bearer token from MCP_API_KEY at runtime. This keeps the raw key out of ~/.codex/config.toml.

3. Verify the server

List configured MCP servers:

codex mcp list

Inspect the saved entry:

codex mcp get private-mcp

In the Codex TUI, use /mcp to see active MCP servers for the current session.

If the server is configured, Codex can expose its tools in CLI sessions and in the Codex IDE extension.

Alternative: config file

You can also add the server directly in ~/.codex/config.toml. For trusted projects, you can scope configuration to the repository with .codex/config.toml.

[mcp_servers.private-mcp]
url = "https://{your-private-mcp-host}/mcp"
bearer_token_env_var = "MCP_API_KEY"

Restart any running Codex session after editing the config file.

Optional controls

Codex supports extra controls for Streamable HTTP MCP servers. Add them only when you need tighter behavior:

[mcp_servers.private-mcp]
url = "https://{your-private-mcp-host}/mcp"
bearer_token_env_var = "MCP_API_KEY"
enabled_tools = ["search", "fetch"]
disabled_tools = ["delete_record"]
default_tools_approval_mode = "prompt"
tool_timeout_sec = 60

[mcp_servers.private-mcp.tools.fetch]
approval_mode = "approve"

Use enabled_tools for allow lists, disabled_tools for deny lists, and default_tools_approval_mode to control whether Codex calls tools automatically or prompts first. Supported approval modes are auto, prompt, and approve.

If your MCP server uses OAuth instead of bearer-token authentication, add the server first, then run:

codex mcp login private-mcp

Troubleshooting

Unauthorized or 401 errors

Make sure MCP_API_KEY is exported in the shell or environment that launches Codex. The key must belong to the same workspace as the private MCP server.

Server not listed

Run codex mcp list. If private-mcp is missing, add it again with the CLI command above or check ~/.codex/config.toml.

Tools not available in a session

Restart Codex after changing MCP config. If you are using the IDE extension, restart the extension or reload the editor window. In the Codex TUI, run /mcp to confirm the server is active.

CLI flags differ from your installed version

Run codex mcp add --help and codex mcp --help. Codex versions can differ, but Streamable HTTP servers should be represented by a URL in config.toml, and bearer auth should use bearer_token_env_var.

Slow responses

Check your network path to the private host and confirm the cloud deployment is healthy. The hostname is specific to your environment, so connectivity issues are usually tied to your cloud provider, DNS, firewall, or deployment status.

Start using tools

Try read-only prompts first:

• "What MCP tools are available from private-mcp?"
• "List the read-only tools before calling any write actions."
• "Use private-mcp to inspect the current workspace context."

For write-capable workflows, ask Codex to explain the proposed action and wait for approval before it calls any mutating tool.

Add reusable workflows

After Codex can reach your MCP server, install Codex skills for repeatable workflows and task-specific instructions. See the Codex Skills quick start.