Codex Integration

Integration with Codex (OpenAI)

Complete guide for connecting MCP Local Memory Service to Codex — OpenAI's AI coding agent.

Prerequisites

• Node.js 20+ installed
• Codex CLI installed (download)
• Internet access for first-time setup

Installation

npm install -g @vheins/local-memory-mcp

Global install gives faster startup and no re-download; then configure the MCP server in Codex (see below).

MCP Server Configuration

Codex stores MCP configuration in config.toml (TOML format, not JSON). There are two levels:

User Level (all projects)

Open ~/.codex/config.toml and add:

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]

If already globally installed:

[mcp_servers.local-memory]
command = "local-memory-mcp"
args = []

Project Level (per project, trusted projects only)

Create .codex/config.toml in the project root with the same [mcp_servers.local-memory] block.

Setup via CLI

# Add MCP server
codex mcp add local-memory -- npx -y @vheins/local-memory-mcp

# List servers
codex mcp list

# Remove server
codex mcp remove local-memory

Setup via TUI (Terminal UI)

Inside a Codex session, /mcp displays all active MCP servers including local-memory.

Environment Variables

Codex uses TOML for env vars:

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]

[mcp_servers.local-memory.env]
PORT = "3456"
STORAGE_PATH = "/custom/path"

Forwarding env vars from the system

Use env_vars to inherit variables from the Codex environment:

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
env_vars = ["HOME", "USER"]

Or with a specific source:

env_vars = [
  "LOCAL_TOKEN",
  { name = "REMOTE_TOKEN", source = "remote" }
]

Tool Approval Mode

Control whether Codex needs to ask permission before calling a tool:

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
default_tools_approval_mode = "prompt"

Mode	Behavior
auto	Auto-approve all tools
prompt	Ask the user each time (default)
approve	Always approve without prompt

Per-tool approval

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
default_tools_approval_mode = "prompt"

[mcp_servers.local-memory.tools.memory-read]
approval_mode = "auto"

[mcp_servers.local-memory.tools.memory-write]
approval_mode = "prompt"

[mcp_servers.local-memory.tools.task-delete]
approval_mode = "approve"

Tool Filter (Allow/Deny List)

# Only these tools may be used
enabled_tools = ["memory-read", "task-read", "standard-read"]

# Disallowed tools (applied after enabled_tools)
disabled_tools = ["memory-delete", "task-delete"]

Temporarily Disable

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
enabled = false

Timeout Configuration

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 60

Verification

codex mcp list

Output:

local-memory — running
  Tools: memory-read, memory-write, task-read, ...

Inside the Codex TUI, open /mcp to check server status, then test the connection by asking:

"Check local memory for this project"

If Codex responds with "No memory" (not an error), the connection is successful.

Running the Dashboard

npx @vheins/local-memory-mcp dashboard
# Open http://localhost:3456

Complete Configuration Example

Here is a complete configuration example for ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.local-memory]
command = "npx"
args = ["-y", "@vheins/local-memory-mcp"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 45
default_tools_approval_mode = "prompt"
enabled_tools = [
  "memory-read", "memory-write",
  "task-read", "task-write",
  "standard-read", "standard-write"
]
disabled_tools = ["memory-delete", "task-delete"]

# Tool-specific approval overrides
[mcp_servers.local-memory.tools.memory-read]
approval_mode = "auto"

[mcp_servers.local-memory.tools.task-read]
approval_mode = "auto"

[mcp_servers.local-memory.tools.memory-write]
approval_mode = "prompt"

[mcp_servers.local-memory.tools.task-write]
approval_mode = "prompt"

Known Limitations

MCP Prompts Not Supported

Codex CLI does not support MCP prompts (the prompts/list and prompts/get capabilities), so prompt templates like memory-agent-core, project-briefing, or task-management-guidelines cannot be invoked as slash commands in Codex.

However, Tools and Resources work fully — you can still use the server's tools directly (e.g. memory-read, memory-write, task-read); only the predefined prompt templates are unavailable. For agents with full prompt support, see MCP Protocol Reference.

Troubleshooting for Codex

• Server not found: check registration with codex mcp list, check PATH (which npx, which local-memory-mcp), and re-add with codex mcp add local-memory -- npx -y @vheins/local-memory-mcp.
• Server error / disconnect: run directly to see errors: npx -y @vheins/local-memory-mcp.
• Configuration not taking effect: Codex reads config.toml — make sure the TOML format is valid (not JSON).
• Slow startup: global install is faster than npx. Codex also supports startup_timeout_sec — increase it if the server needs more time.

References

• Codex MCP Documentation
• Codex Config Reference
• MCP Local Memory — Getting Started
• Tool Reference & Usage Guide
• Troubleshooting Guide
• Integrasi dengan Codex — Bahasa Indonesia