To connect Codex to an MCP router, add the router’s reachable Streamable HTTP URL with codex mcp add, then verify it with codex mcp list. For a local process, configure stdio instead. The correct choice depends on where the router runs, how Codex can reach it, and how it authenticates clients.
What you are connecting
The Model Context Protocol (MCP) lets an AI client discover and call tools exposed by a server. An MCP router can present one endpoint that forwards requests to one or more tool providers. Codex connects to that endpoint, performs initialization, discovers the advertised tools, and sends structured calls when you ask it to use them.
This guide covers the current Codex setup pattern documented for Streamable HTTP, plus stdio for processes Codex can launch itself. Command names, supported transports, and authentication options can change, so confirm the labels in the Codex version you are running.
Choose the connection path first
| Option | Use it when | Checks before setup |
|---|---|---|
| HTTP / Streamable HTTP | Your router already runs at a URL reachable from Codex | Exact endpoint, network access, HTTP authentication, and Streamable HTTP support |
| stdio | Codex can start the router process in its own environment | Installed executable, dependencies, arguments, environment variables, and an existing absolute working directory |
| Secure MCP Tunnel | The router is private, on-premises, or behind a firewall | The tunnel client runs inside the network boundary and stays healthy |
| Public development tunnel | You are temporarily testing a local endpoint | Intentional public exposure and development-appropriate server security |
HTTP does not make a private server reachable by itself. The environment where Codex runs must be able to resolve and connect to the URL. For a local-only router, either run it through stdio or provide a network path such as a private tunnel.
#1 Best Overall
- 【4 Ports USB 3.0 Hub】Acer USB Hub extends your device with 4 additional USB 3.0 ports, ideal for connecting USB peripherals such as flash drive, mouse, keyboard, printer
- 【5Gbps Data Transfer】The USB splitter is designed with 4 USB 3.0 data ports, you can transfer movies, photos, and files in seconds at speed up to 5Gbps. When connecting hard drives to transfer files, you need to power the hub through the 5V USB C port to ensure stable and fast data transmission
- 【Excellent Technical Design】Build-in advanced GL3510 chip with good thermal design, keeping your devices and data safe. Plug and play, no driver needed, supporting 4 ports to work simultaneously to improve your work efficiency
- 【Portable Design】Acer multiport USB adapter is slim and lightweight with a 2ft cable, making it easy to put into bag or briefcase with your laptop while traveling and business trips. LED light can clearly tell you whether it works or not
- 【Wide Compatibility】Crafted with a high-quality housing for enhanced durability and heat dissipation, this USB-A expansion is compatible with Acer, XPS, PS4, Xbox, Laptops, and works on macOS, Windows, ChromeOS, Linux
Connect a reachable HTTP MCP router
1. Add the server from the command line
Replace my_router with a short local name and replace the example URL with the router’s MCP endpoint:
codex mcp add my_router --url https://example.com/mcpThe name is your local label; it does not have to match the server’s hostname. Use the MCP endpoint itself, not a marketing page, health-check page, or unrelated API base URL.
2. Verify the entry
codex mcp listConfirm that the server appears with the expected name and URL. This proves that Codex has a configuration entry; it does not by itself prove that the endpoint is reachable, authenticated, or advertising usable tools.
3. Start a session and test discovery
Ask Codex to inspect the connected MCP tools or invoke one harmless read-only tool. A successful test should show that initialization completes and that the router returns a tool list or a valid tool result. Start with a low-risk call before testing actions that modify data.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRank #2
- The Anker Advantage: Join the 80 million+ powered by our leading technology.
- SuperSpeed Data: Sync data at blazing speeds up to 5Gbps—fast enough to transfer an HD movie in seconds.
- Big Expansion: Transform one of your computer's USB ports into four. (This hub is not designed to charge devices.)
- Extra Tough: Precision-designed for heat resistance and incredible durability.
- What You Get: Anker Ultra Slim 4-Port USB 3.0 Data Hub, welcome guide, our worry-free 18-month warranty and friendly customer service.
Configure the same server in config.toml
You can add a server block directly to ~/.codex/config.toml:
[mcp_servers.my_server]
url = "https://example.com/mcp"Use the same endpoint and local name you would use with the CLI. Keep the file’s TOML syntax exact: quote the URL, use a simple section name, and avoid duplicate sections with the same name. After saving, run codex mcp list again.
Connect a local router over stdio
stdio is appropriate when Codex can launch the MCP server process directly. The command, dependencies, arguments, and environment must all exist in Codex’s execution environment, not merely on your personal workstation.
Required stdio details
- Executable: the server command must be installed and executable.
- Dependencies: runtimes, packages, certificates, and native libraries must be available.
- Arguments: pass the router’s required startup flags exactly.
- Environment: provide noninteractive configuration and credentials through environment variables where appropriate.
- Working directory: use an existing absolute path. Relative or nonexistent directories commonly prevent startup.
Use the stdio configuration fields exposed by your Codex release for the command, arguments, environment, and absolute working directory. Do not assume that an HTTP URL can be substituted for a stdio command; they are different transports.
Rank #3
- 4 USB Ports Expansion: This USB Hub turns 1 USB A port into 4 USB A ports with your devices for mouses, keyboards, U disks, flash drives, and more USB Peripherals. Greatly improve your work efficiency
- Transfer Files in Seconds: The USB 3.0 Hub supports a max file transfer speed of 5Gbps. That's fast enough to transfer a 10 GB file in just 16.4 seconds
- Plug and Play: No additional drivers or software are required. The USB multiport adapter is plug-and-play for Windows, macOS, Linux, Chrome OS, and More
- Wide Compatibility: In addition to laptops and desktop computers, this USB 3.0 splitter also supports other devices with USB A such as Xbox Series, PS5, car systems, etc., which can meet the various needs of your daily life
- Compact Mini Size: This USB A hub is designed to be very compact and portable, which is only 0.4 inches thick and 33g heavy. It is very suitable for your travel and business trips
Private and local routers
Secure MCP Tunnel
For a router that must remain private, OpenAI documents Secure MCP Tunnel. Run the tunnel client in the same trust boundary that can already reach the router. It can connect to an HTTP URL or launch/reach a server over stdio. Keep the client running and healthy while Codex is using the connection; a stopped or expired tunnel looks like an endpoint outage from Codex’s perspective.
Temporary public tunneling
The official MCP quickstart demonstrates ngrok as a development example for exposing a local Streamable HTTP endpoint. Treat this as a temporary testing pattern, not a default production architecture. Public exposure changes who can attempt to reach the router, so configure authentication and restrict the server’s capabilities before sharing the URL.
Authentication without leaking secrets
An anonymous router needs no credentials. An authenticated HTTP router may require authorization or other headers, depending on its implementation and the connection method supported by your Codex version. OpenAI’s connection guidance also describes reusable credentials from OpenAI-origin connections through vault-backed storage.
For stdio, pass secrets through environment variables available to the server process rather than embedding them in shared agent definitions. Never place tokens in plugin archives, screenshots, shell history copied into tickets, or logs that other people can read. Verify which environment actually launches the process: a variable set in your interactive terminal may not exist in a managed Codex runtime.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Smart Charging Ports: 2 Extra 5V/2.4A charging ports supporting 2.4A output specially designed for smart charging. Charges most USB charging equipment, regardless of large batteries such as smartphones or tablets, or mini-battery equipment such as smart portable devices, at full speed.
- Faster Speed with USB 3.0: USB 3.0 ports offer transfer speeds of up to 5Gbps, 10 times faster than USB 2.0. This 7-port USB 3.0 data hub can instantly expand 1 USB 3.0 port to 7 USB 3.0 data ports for keyboard, mouse, printer, hard drivers and other USB devices.
- TP-Link Charging technology intelligently identifies connected devices, automatically delivering the smart charge to your smartphones, tablets or devices with a USB charging connector, minimizing charging time.
- Protect Both Your Equipment and Your Data: UH720 has a sophisticated circuit design with multiple overheat, overload, overvoltage and short circuit protections. A built-in surge protector keeps both your devices and your data safe in the data transfer process.
- UH720 supports hot-swap USB ports that can be safely connected and disconnected while the computer is on and running.
Diagnose a connection that fails
It does not appear in codex mcp list
- Run the add command again with the intended name and URL.
- Inspect
~/.codex/config.tomlfor a spelling error, malformed TOML, or a duplicate section. - Make sure you are checking the same user profile and environment in which Codex runs.
The entry exists but never initializes
- Check that the URL is the MCP endpoint and supports Streamable HTTP.
- Test DNS, routing, firewall rules, and TLS from the Codex environment.
- Confirm that required authorization values are present and unexpired.
- Check the router’s server logs for rejected initialization requests.
HTTP works from your laptop but not from Codex
Reachability is evaluated from the connecting environment. A private hostname, VPN route, IP allowlist, or corporate proxy available on your laptop may not exist where Codex runs. Move the connection into the permitted network, expose it through an approved private tunnel, or use stdio where the process can run locally.
stdio exits immediately
- Run the exact command manually in the same environment.
- Check that the executable is on the expected path and that every dependency is installed.
- Replace a relative working directory with an existing absolute path.
- Inspect process stderr and server logs.
- Verify that required environment variables are present and that the process does not wait for interactive input.
Tools appear, but calls fail
Separate discovery from invocation. Compare the advertised schema with the arguments being sent, then try a representative read-only call and an intentionally invalid call in MCP Inspector. The official server guidance recommends inspecting initialization, advertised tools, schemas, results, errors, and annotations. This identifies whether the defect is in router forwarding, a tool implementation, or Codex configuration.
A repeatable validation checklist
- Identify whether the router is HTTP, stdio, or private behind a firewall.
- Confirm the endpoint or executable is reachable from the Codex environment.
- Add the server with
codex mcp addor editconfig.toml. - Run
codex mcp listand verify the name and connection details. - Check authentication without placing secrets in shared files or logs.
- Start a session and confirm initialization.
- Inspect the advertised tools and schemas.
- Run a harmless read-only call, then investigate errors using router logs and MCP Inspector.
Performance, reliability, and operating costs
Every call crosses the network when you use HTTP, so latency includes DNS, TLS, tunnel overhead, router dispatch, and the downstream tool. Keep the router and tunnel client close to the systems they access when possible. For stdio, process startup and dependency loading can dominate the first request; a long-running process avoids repeated cold starts.
Design for partial failure. A router may be reachable while one downstream tool is unavailable, or initialization may succeed while a specific call times out. Return clear errors from the router, set sensible downstream timeouts, and log request identifiers without logging credentials or sensitive tool arguments. During upgrades, validate initialization and one representative call before directing production traffic to the new endpoint.
Best Value
- 【4 Ports USB Port Hub】：Expand one USB-A port into four USB ports with VIENON USB splitter 1 in 4 out. Connect keyboards, mice, flash drives, printers, card readers and other USB devices to your laptop or desktop easily.
- 【5Gbps USB 3.0 Fast Data Transfer】：This USB adapter includes a USB 3.0 data port with transfer speeds up to 5Gbps, helping you move photos, files and videos faster than USB 2.0. Additional USB ports are suitable for keyboard, mouse, printer and other standard USB accessories.
- 【Plug and Play, No Driver Needed】：No software or external driver is required. Just plug the USB multiport adapter into your computer and start using it. Compatible with Windows, macOS, Linux, laptops, desktops, Xbox, PS4 and more USB-A host devices.
- 【Ultra Slim and Travel Friendly】：The compact usb hub for laptop features a slim body that saves desk space and fits easily in a laptop bag, backpack or office drawer. The spacing between USB ports is designed for common USB devices, allowing multiple connections at the same time.
- 【LED Indicator and Daily Use Design】：A soft blue LED indicator lets you quickly check working status without being too bright. Please note: this usb multiport adapter is designed for data transfer and low-power peripherals only. It does not support charging laptops, tablets or high-power devices.
Or skip the browser setup
If the MCP tool you need is website capture, ScreenshotNeo exposes an MCP server for Claude, Cursor, and other MCP clients. Its tools include take_screenshot, get_page_info, and capture_pdf, so an AI agent can request captures without you wiring a browser locally. It removes cookie-consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed as clean shots. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots.
For a direct API call, see the ScreenshotNeo documentation:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo also supports full-page captures, CSS-selector element shots, device presets, custom viewports, dark mode, retina scale, PDFs, custom CSS and JavaScript, waits, request blocking, headers, cookies, geolocation, caching, signed links, asynchronous jobs, bulk capture, and a usage API. Every response identifies the page verdict and whether it was billed. Create a free ScreenshotNeo account to get started.
When to use which setup
- Choose Streamable HTTP when the router is already hosted and reachable.
- Choose stdio when Codex can reliably launch the process and its dependencies.
- Choose Secure MCP Tunnel when the router must stay inside a private network.
- Use a public tunnel only for controlled development testing.
Frequently Asked Questions
Does adding an MCP server install its tools locally?
No. The configuration tells Codex where the server is and how to connect; the server remains responsible for implementing and advertising its tools.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCan one Codex configuration contain multiple routers?
Yes. Give each server a distinct local name and configure each endpoint or stdio process separately.
What should I test first after connecting?
Test initialization, inspect the advertised schemas, and run a harmless read-only tool call before attempting changes.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
