Skip to content
Aptos Documentation

Setting up Aptos MCP with Codex
  1. Install OpenAI Codex.
Terminal window
npm install -g @openai/codex

On macOS you can also run brew install codex.

  1. Obtain your APTOS_BOT_KEY from Geomi (Bot Keys in the account menu). See Aptos MCP for the full steps.

  2. Navigate to your project:

Terminal window
cd your-awesome-project
  1. Add the Aptos MCP server:
Terminal window
codex mcp add aptos-mcp --env APTOS_BOT_KEY=<your_bot_key> -- npx -y @aptos-labs/aptos-mcp

Replace <your_bot_key> with the key from step 2. You can pass additional --env NAME=VALUE pairs if needed.

  1. Confirm the server is registered:
Terminal window
codex mcp list

You should see aptos-mcp in the list.

  1. Start Codex:
Terminal window
codex

  1. Run /mcp inside Codex and confirm aptos-mcp is listed.

  2. Prompt the agent with what aptos mcp version are you using? to verify the connection. It should report the currently published @aptos-labs/aptos-mcp version from the MCP Server Card.

Alternative: TOML configuration

Section titled “Alternative: TOML configuration”

If the CLI command fails, edit ~/.codex/config.toml (in the IDE: gear icon → MCP settings → Open config.toml) and add:

~/.codex/config.toml
[mcp_servers.aptos-mcp]
command = "npx"
args = ["-y", "@aptos-labs/aptos-mcp"]


[mcp_servers.aptos-mcp.env]
APTOS_BOT_KEY = "<your_bot_key>"

Save the file and restart Codex. Do not commit the Bot Key.