kaiva BRIDGE
CLIENT SETUP

How to add a remote MCP server to Codex (config.toml)

Updated

Add an [mcp_servers.<name>] table to ~/.codex/config.toml with the server's url and an Authorization header carrying a gateway key. Codex reads the file when it starts.

Start freeRead the docs

Step by step

  1. Create a keyOn the server's Connect tab, choose Codex and create a key. It is shown once.
  2. Edit config.tomlPaste the block below into ~/.codex/config.toml, with your server's address and key.
  3. Use itStart Codex and ask it to use one of the server's tools.

Codex config.toml for a remote MCP server

A gateway key (kv_live_...) calls one server. Create it on the server's Connect tab or under Keys & access. It is shown once; Bridge keeps only its hash.

~/.codex/config.toml
[mcp_servers.your-server]
url = "https://api.kaiv.ai/api/bridge/mcp/your-server"
http_headers = { "Authorization" = "Bearer kv_live_..." }

If it does not connect

The key must be a gateway key (kv_live_...) for this server, and the server must be published. Then run the CLI's check:

Terminal
npx @kaiva/bridge doctor your-server

Other ways to do it

  • A local server over stdioCodex can also start a server on your machine from a command in the same file. It runs only where it is installed.

Questions

Where is Codex's MCP configuration?
In ~/.codex/config.toml, one [mcp_servers.<name>] table per server.
Does the whole block go into config.toml?
Yes. It is valid TOML as copied from the server's Connect tab.

Related