MCP server

The quickest way is the one-prompt setup: your agent connects itself and you sign in once in the browser. To set it up yourself, or with an API key, use the steps for your tool below.

The MCP server is at https://api.proxymail.qa/mcp (Streamable HTTP). Send the key as a bearer token.

Claude Code

claude mcp add --transport http proxymail-qa https://api.proxymail.qa/mcp --header "Authorization: Bearer $PROXYMAIL_QA_API_KEY"

Cursor

The quickest way is Add to Cursor on Proxy Mail QA’s Cursor Directory page, which installs the server and a skill; then log in to it from the MCP section of Cursor Settings. To use an API key instead, in .cursor/mcp.json:

{
  "mcpServers": {
    "proxymail-qa": {
      "url": "https://api.proxymail.qa/mcp",
      "headers": { "Authorization": "Bearer qa_…" }
    }
  }
}

GitHub Copilot in VS Code

In .vscode/mcp.json, or your user mcp.json. VS Code asks for the key the first time and stores it securely, so it never sits in the file:

{
  "inputs": [{ "id": "proxymail-qa-key", "type": "promptString", "description": "Proxy Mail QA API key", "password": true }],
  "servers": {
    "proxymail-qa": {
      "type": "http",
      "url": "https://api.proxymail.qa/mcp",
      "headers": { "Authorization": "Bearer ${input:proxymail-qa-key}" }
    }
  }
}

Copilot cloud agent

On GitHub.com, save the key as an Agents secret named COPILOT_MCP_PROXYMAIL_QA_KEY, then in the repository’s Settings → Copilot → MCP servers:

{
  "mcpServers": {
    "proxymail-qa": {
      "type": "http",
      "url": "https://api.proxymail.qa/mcp",
      "headers": { "Authorization": "Bearer $COPILOT_MCP_PROXYMAIL_QA_KEY" },
      "tools": ["create_address", "wait_for_code", "wait_for_link", "check_delivery", "list_addresses", "update_address"]
    }
  }
}

The cloud agent runs listed tools without asking, so this list leaves out delete_address.

Google Antigravity

In the agent panel, open … → MCP Servers → Manage MCP Servers → View raw config, add the server, then restart Antigravity. Antigravity uses serverUrl for remote servers:

{
  "mcpServers": {
    "proxymail-qa": {
      "serverUrl": "https://api.proxymail.qa/mcp",
      "headers": { "Authorization": "Bearer qa_…" }
    }
  }
}

OpenAI Codex

Codex reads the key from your environment:

codex mcp add proxymail-qa --url https://api.proxymail.qa/mcp --bearer-token-env-var PROXYMAIL_QA_API_KEY

Android Studio and Xcode

Gemini in Android Studio (agent mode) supports remote MCP servers. Add the server to its MCP configuration as an httpUrl, then sign in when it asks:

{
  "mcpServers": {
    "proxymail-qa": { "httpUrl": "https://api.proxymail.qa/mcp" }
  }
}

Xcode: Claude Code and Codex can use Xcode’s own tools (xcrun mcpbridge) alongside Proxy Mail QA, and Claude Code Desktop can run your app in its iOS Simulator pane and sign up in it. Xcode’s built-in agents can add MCP servers and plug-ins too. All of it is in iOS apps with a coding agent; for UI tests, see Mobile apps.

Other clients

Other clients that support remote MCP servers with headers, such as Windsurf, work the same way.

Claude and ChatGPT

Claude (claude.ai and the Claude apps) and ChatGPT sign in by browser, with no key to copy. Add a custom connector with the address https://api.proxymail.qa/mcp. You’ll be sent to Proxy Mail QA to sign in, choose the project it may use, and allow it. In Claude: Settings → Connectors → Add custom connector. In ChatGPT: Settings → Apps & Connectors, with developer mode on.

A connected app gets a token for that one project: it can create and delete test addresses, give a new one a password for a sign-up form, and read their codes and links, but not passwords saved earlier. It’s listed under Project settings → API keys as a connected app; disconnect it there at any time. Other MCP clients that support OAuth sign-in work the same way.

Tools

Tool	What it does
`get_project`	The project it works in: default mail domain and the others, email prefix, limits
`create_address`	A new test address, with a fictional name and username for sign-up forms, a date of birth for an `age` (such as `under13`), a `country` (such as `GB`), and a password if asked (`password: true`). `site` and `environment` record where it’s used, as the Chrome extension does, and show on the account in the app
`form_values`	For a form with more than an email field: give it what the page says about each field, and get what to type or pick in each, from a new address made for it (a username and password that fit the rules, the date of birth in the field’s format, a country the drop-down offers). The agent fills in the form
`wait_for_code`	Waits up to 30 seconds for a verification or login code and returns it. `unused: true` skips a code already used
`wait_for_link`	The same for a verify, magic sign-in, invite or password-reset link. `app: true` asks for the link that opens a mobile app (`myapp://…`) when the email also has a web one
`get_address_variants`	Unusual versions of an address for testing sign-up forms: ones whose mail still arrives (capitals, plus tags with special characters), and invalid ones (more)
`check_delivery`	Explains an address’s mail without waiting: what reached it, anything we refused, and the likely cause when nothing did
`list_addresses`	The project’s addresses, each with its persona, tags and newest code or link. Filters find a test account made earlier: `tags`, `country`, `min_age` and `max_age`, `has_password`, `search`, `site` and `environment`
`update_address`	Its first name, last name, username, date of birth or country, if the app changed them, and notes, tags or a label: what the test account was for
`set_password`	Saves the password the test account uses now, after the app changed or reset it; leave it out to generate one
`delete_address`	Deletes an address and its mail
`get_saved_password`	Only for keys allowed to read saved passwords
`get_sign_in`	Signs in again as a saved test account in one call: the account for this `site` (with any `tags` and `environment` given) and its password, as the extension’s sign-in list picks it. Only for keys allowed to read saved passwords
`mark_dev_host`	Marks a host such as `localhost:3000` as a dev environment of the project, so `check_email` passes links to it instead of failing them
`check_email`	Checks an email that arrived: SPF, DKIM and DMARC, links to localhost or plain http, where its link goes (`expect_host`), a stated expiry, a plain-text part, its size, and given phrases (`expect_text`) and its language (`expect_language`). Verdicts only, never the email
`count_emails`	How many emails arrived (`since`, `type`, `subtype`), each summarised without its content: for “exactly one verification email”
`expect_no_email`	Watches for up to 30 seconds and passes if nothing arrives: for “an unsubscribed user gets nothing”
`check_out_account`, `extend_checkout`, `return_account`	Borrow a test account in a known state (by `tags`, `country`, age or a saved password) that no other test has, and give it back, recording what changed (more)
`start_run`, `add_run_note`, `finish_run`	Record a session as a run: pass `run_id` (and `test`, the step it belongs to) to the tools and `finish_run` returns the report in Markdown, for the person or a pull request (more)

Prompts

Ready-made checklists the agent follows with these tools and its own browser tools. The tests end in a run’s report. Pick one where your client lists MCP prompts (in Claude Code, type / and look for proxymail-qa):

Prompt	What it does
`test_signup_flow`	Signs up at the page you give with a new address, finishes the verification, checks the email and counts duplicates
`test_password_reset`	Borrows a verified account, resets its password through the app, checks the reset email, saves the new password and returns the account
`test_sign_in_code`	Borrows a verified account and signs in with the code or magic link the app emails
`prepare_account`	Borrows an account with the tags you give, confirms in the app that it’s in the state the test needs (“on the premium plan, with no orders”), makes a new one at the sign-up page you give when none is free, and puts it back after the test
`auth_regression_pack`	The same steps every time for sign-up, password reset and invitations, including link reuse and replaced links, each step named in the run; the report says what changed since the last runs of the pack. Also an agent skill
`audit_auth_emails`	Triggers each account email the app sends (verification, reset, sign-in, email change), checks every one and lists what to fix

Use it

Then ask in plain words: “Sign up on localhost:3000 with a new Proxy Mail QA address and confirm the email.”

Some AI agents, including Claude, will only sign up on an app running on your computer (localhost). For a staging or production site, ask the agent to write a Playwright or Cypress test that uses the API, and run it yourself or in CI. To test something by hand instead, Proxy Mail QA for Chrome fills the sign-up form with a test account and shows the code or link right in the page.

A skill for Claude Code and other agents describes the whole flow.