Codex remote setup (HTTP with OAuth)

Neotoma with Codex · Remote setup for Codex sandboxes that cannot run local Neotoma.

Running Codex on the same machine as Neotoma? See Codex local setup (stdio).

Setup

Codex sandboxes can connect to remote MCP servers over HTTP. Use this when Neotoma is not installed locally in the sandbox. Start with local install on your host machine, then configure remote access:

Start Neotoma with a tunnel: follow the tunnel guide to expose your local Neotoma instance over HTTPS. The quickest path:
Code snippet
Copy the exact snippet shown below.
```
neotoma api start --env prod --tunnel
```
Configure HTTP transport with OAuth in your Codex config. Replace the URL with your tunnel URL
Code snippet
Copy the exact snippet shown below.
```
# .codex/config.toml
[mcp_servers.neotoma]
type = "http"
url = "https://<tunnel-host>/mcp"
```
Codex handles the MCP OAuth authorization flow automatically.

When MCP is not available in the sandbox, agents can use the neotoma CLI directly as a fallback.

Back to Neotoma with Codex · Install guide · MCP reference