# Connect Hallway Test to Cursor

> Add the Hallway Test MCP server to Cursor: one entry in mcp.json and a Google sign-in, then your agent can send a real user to test what it just built.

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

Cursor talks to remote MCP servers over HTTP and handles the OAuth sign-in for you. Add one entry to mcp.json, authorize once, and the 11 Hallway Test tools show up in Agent mode.

## Add the server in Cursor

1. **Open the MCP configuration.** In Cursor, open Cursor Settings and go to the MCP section, then choose Add new MCP server. Or edit the file directly: ~/.cursor/mcp.json makes the server available in every project, .cursor/mcp.json inside a repository limits it to that project.

2. **Add Hallway Test.** Paste this entry. There are no headers or API keys to fill in: Hallway Test uses OAuth, so Cursor asks you to sign in instead.

   ```json
   {
     "mcpServers": {
       "hallwaytest": {
         "url": "https://mcp.hallwaytest.ai/mcp"
       }
     }
   }
   ```

3. **Sign in.** Back in the MCP list, Hallway Test shows a Needs login state. Click it: your browser opens the Hallway Test sign-in, sign in with Google and approve the connection. Cursor registers itself with the server automatically, so there is nothing to paste back.

4. **Check the tools.** Once the indicator next to the server turns green, expand it. You should see 11 tools, from plan_usability_test_suite to jam_get_network_requests. If the list stays empty, toggle the server off and on.

5. **Run your first test.** Open Agent mode and 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.
   ```

6. **You’re all set.** Cursor 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 Cursor

### 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

**Cursor never opens the browser to sign in**
Update Cursor to the current version; some builds skipped the OAuth step for remote servers. Then remove the entry, add it again and click Needs login. Cursor receives the sign-in on http://localhost:8787/callback, so that port has to be free on your machine.

**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.

**The tools are listed, but calls fail with an authorization error**
The token has expired. Click the server in the MCP list and sign in again; your configuration stays as it is.

**Can I share the configuration with my team?**
Yes. Commit .cursor/mcp.json to the repository. The entry contains only the server URL; every teammate signs in with their own Google account the first time.

## Other clients

- [Connect Hallway Test to Claude](https://hallwaytest.ai/connect-mcp.md)
- [Connect Hallway Test to Codex](https://hallwaytest.ai/connect-codex.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.