# Connect Hallway Test to Codex

> Add the Hallway Test MCP server to OpenAI Codex with two commands, codex mcp add and codex mcp login. Works in the Codex CLI and the IDE extension.

Page: https://hallwaytest.ai/connect-codex
MCP endpoint: https://mcp.hallwaytest.ai/mcp
Last updated: September 26, 2026

Codex supports remote MCP servers with OAuth out of the box. Two commands register Hallway Test and sign you in; the 11 tools are then available in every Codex session, in the terminal and in the IDE extension.

## Add the server in Codex

1. **Add the server from the CLI.** Run this in your terminal. Codex writes the entry to ~/.codex/config.toml.

   ```bash
   codex mcp add hallwaytest --url https://mcp.hallwaytest.ai/mcp
   ```

2. **Or add it to config.toml by hand.** The same entry in ~/.codex/config.toml. No token variable is needed: Hallway Test uses OAuth.

   ```toml
   [mcp_servers.hallwaytest]
   url = "https://mcp.hallwaytest.ai/mcp"
   ```

3. **Sign in.** Codex opens your browser: sign in with Google and approve the connection. Codex registers itself with the server automatically, so no client ID is required.

   ```bash
   codex mcp login hallwaytest
   ```

4. **Check the connection.** codex mcp list shows hallwaytest with its URL. In a Codex session, ask What Hallway Test tools do you have? and you should get the 11 tools back.

   ```bash
   codex mcp list
   ```

5. **Using the IDE extension instead.** Open the gear menu, choose MCP servers, then Add server and Streamable HTTP. Enter hallwaytest as the name and https://mcp.hallwaytest.ai/mcp as the URL, restart the extension, and choose Authenticate when prompted.

6. **Run your first test.** Describe the flow in one sentence, for example:

   ```bash
   Use Hallway Test to have a real user place an order as a guest on https://staging.example.com and reach the confirmation page.
   ```

7. **You’re all set.** Codex calls create_usability_task and waits for the recording with wait_for_usability_result; results come back within 24 hours. When the session is ready, ask it to audit the recording and fix what the tester got stuck on.

## Account activation

A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account and tests start immediately, with no need to reconnect. Book the pilot call: https://hallwaytest.ai/book

## What Hallway Test exposes to Codex

### Run a test

- `create_usability_task`: Writes and dispatches a real usability test to a real user, based on the flow you describe.
- `wait_for_usability_result`: Waits for the tester to finish and hands back the session recording as soon as it’s ready.
- `cancel_test_run`: Cancels a test that was already dispatched.

### Plan tests

- `plan_usability_test_suite`: Scans your project and drafts a full test suite – 5 to 10 critical user flows, ranked by risk.

### Analyze a recording

- `plan_jam_ux_audit`: Turns a raw recording into a structured, evidence-backed UX audit by running the tools below in the right order.
- `jam_get_details`: Recording metadata – type, duration, whether a voice transcript exists, and the shareable link.
- `jam_get_user_events`: The full click / type / navigation log – the source of truth for what the tester actually did.
- `jam_get_video_transcript`: The tester’s spoken think-aloud commentary, timestamped.
- `jam_get_frames`: Pulls screenshots from key moments in the recording to visually confirm a friction point.
- `jam_get_console_logs`: Browser console logs, used to explain a technical cause behind friction that’s already been proven.
- `jam_get_network_requests`: Network request log, used to trace a failed call behind an already-evidenced UX problem.

## Troubleshooting

**codex mcp login says the server is unknown**
The name must match the entry: codex mcp list shows the names Codex knows. If the entry is missing, check ~/.codex/config.toml for a typo in the [mcp_servers.hallwaytest] header.

**Hallway Test replies with a link to book a call instead of running the test**
Your account is connected but not activated yet. Activation happens on the free pilot call; book it through the link, and after the call every test dispatch goes through without reconnecting.

**Calls fail with an authorization error after some time**
Run codex mcp login hallwaytest again. The configuration stays in place; only the sign-in is refreshed.

**Does this work with Claude Code as well?**
Yes, with one command: claude mcp add --transport http hallwaytest https://mcp.hallwaytest.ai/mcp. Claude Code opens the same Google sign-in.

## Other clients

- [Connect Hallway Test to Claude](https://hallwaytest.ai/connect-mcp.md)
- [Connect Hallway Test to Cursor](https://hallwaytest.ai/connect-cursor.md)
- Claude Code (CLI): `claude mcp add --transport http hallwaytest https://mcp.hallwaytest.ai/mcp`

## Related

- [Home](https://hallwaytest.ai/index.md)
- [Pricing](https://hallwaytest.ai/pricing.md)
- [Book a free pilot](https://hallwaytest.ai/book.md)

Stuck partway through? Write to support@hallwaytest.ai.