--- title: "MCP server | Proxy Mail QA" description: "Connect Claude Code, Cursor, Copilot, Codex, Claude or ChatGPT to Proxy Mail QA's MCP server: tools to create test addresses and wait for codes and links." url: https://proxymail.qa/docs/mcp --- # MCP server The quickest way is the [one-prompt setup](https://proxymail.qa/docs/api#agent-setup): your agent connects itself and you sign in once in the browser. To set it up yourself, or with an [API key](https://proxymail.qa/docs/api-keys), 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 Terminal window ```bash 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](https://cursor.directory/plugins/proxymail-qa), 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`: ```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: ```json { "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**: ```json { "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: ```json { "mcpServers": { "proxymail-qa": { "serverUrl": "https://api.proxymail.qa/mcp", "headers": { "Authorization": "Bearer qa_…" } } } } ``` ## OpenAI Codex Codex reads the key from your environment: Terminal window ```bash 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: ```json { "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](https://proxymail.qa/docs/ios-agents); for UI tests, see [Mobile apps](https://proxymail.qa/docs/mobile). ## 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](https://proxymail.qa/docs/unusual-addresses)) | | 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](https://proxymail.qa/docs/rest-api#an-account-pool-for-parallel-tests)) | | 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](https://proxymail.qa/docs/rest-api#runs-a-report-for-the-pull-request)) | ## 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](https://proxymail.qa/.well-known/agent-skills/auth-regression-pack/SKILL.md) | | 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](https://proxymail.qa/docs/playwright) or [Cypress](https://proxymail.qa/docs/cypress) test that uses the API, and run it yourself or in CI. To test something by hand instead, [Proxy Mail QA for Chrome](https://proxymail.qa/chrome-extension) 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](https://proxymail.qa/.well-known/agent-skills/proxymail-qa/SKILL.md) describes the whole flow. [Previous API keys](https://proxymail.qa/docs/api-keys.html) [Next REST API](https://proxymail.qa/docs/rest-api.html)