---
title: "VS Code Copilot and the iOS simulator: MCP setup | Mobster"
description: "Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator."
canonical: "https://mobster.dev/connectors/vs-code"
last-updated: "2026-10-08"
---

Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator.

# VS Code Copilot and the iOS simulator: MCP setup

Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator.

## The short version, with Mobster for Mac in Applications

```
code --add-mcp "{\"name\":\"mobster\",\"command\":\"/Applications/Mobster.app/Contents/MacOS/mobster-agent\",\"args\":[\"mcp\"]}"
```

Config file: .mcp.json at the workspace root, or ~/.copilot/mcp-config.json

**VS Code** by Microsoft

Status From Microsoft’s docs, read 8 October 2026

Setup One command

Docs [Microsoft’s MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

Download for Mac

See pricing

On this page

1. [Install Mobster for Mac](#install-mobster-for-mac)
2. [Add the server](#add-the-server)
3. [Check it’s connected](#check-its-connected)
4. [A first check: picking an answer](#a-first-check-picking-an-answer)
5. [Tell Copilot to verify every change](#tell-copilot-to-verify-every-change)
6. [Use a real iPhone](#use-a-real-iphone)
7. [Troubleshooting](#troubleshooting)
8. [Questions](#questions)
9. [Sources](#sources)

*A check file open in a code editor, the coding agent running it through Mobster: verify start, tap Check, verify finish. Failed, 2 of 3 passed. On the iPhone, the app's streak screen still shows 3 days, not 4.*

What VS Code gets back from mobster verify on your app: the lesson and its “Great job!” pass, but the streak stays at 3, so the check fails.

GitHub Copilot’s agent mode in VS Code can edit your SwiftUI views, but it can’t see the simulator. Add Mobster’s MCP server and Copilot gets tools to run your app on a headless iOS simulator, read each screen as a list of controls by name, tap and type, and finish with a verdict of passed or failed from assertions on the accessibility tree. The same server can drive a real iPhone plugged into your Mac.

You need an Apple silicon Mac with macOS 15 or later and Xcode with an iOS Simulator runtime. A real iPhone also needs Developer Mode and the WebDriverAgent runner, set up in Mobster for Mac ([Device setup](https://docs.mobster.dev/device-setup)).

## Install Mobster for Mac

[Get Mobster for Mac](https://mobster.dev/download), drag it to Applications and open it. Its MCP server is the agent inside the app, so the command every client starts is this path, with `mcp`:

```
/Applications/Mobster.app/Contents/MacOS/mobster-agent
```

The first check creates Mobster’s own simulator, boots it headless and builds WebDriverAgent, once per Xcode version. Mobster never touches your own simulators: each one it creates has a name that starts with “Mobster”.

## Add the server

VS Code reads two formats, and they differ in one word. Get the word wrong and the server never loads.

The portable format, which the MCP: Add Server command now prefers, goes in `.mcp.json` at the workspace root (for the project) or `~/.copilot/mcp-config.json` (for you), under `mcpServers`:

```
{  "mcpServers": {    "mobster": {      "type": "stdio",      "command": "/Applications/Mobster.app/Contents/MacOS/mobster-agent",      "args": ["mcp"]    }  }}
```

The VS Code format goes in `.vscode/mcp.json` or your user profile, under `servers`. It still works, and the Add Server flow lists it as deprecated:

```
{  "servers": {    "mobster": {      "type": "stdio",      "command": "/Applications/Mobster.app/Contents/MacOS/mobster-agent",      "args": ["mcp"]    }  }}
```

VS Code’s field table marks `type` as required for a local server while its examples leave it out, so both blocks include it. From a terminal, this adds the server to your user profile:

```
code --add-mcp "{\"name\":\"mobster\",\"command\":\"/Applications/Mobster.app/Contents/MacOS/mobster-agent\",\"args\":[\"mcp\"]}"
```

VS Code’s docs say `command` must be on the system path or a full path, so the blocks use the agent’s full path.

For Smart, where Mobster runs the steps itself on your OpenAI or Anthropic key, add `"--env-file", "~/.config/mobster/agent.env"` after `"mcp"` in `args`. Mobster expands the `~`. Key-less checks, where Copilot drives, need no key.

VS Code’s MCP pages don’t document a tool-call timeout. Mobster doesn’t rely on one: every call returns within 45 seconds and `wait` within 50, and slow work such as the first simulator boot continues under a `run_id` that Copilot polls with `wait`.

## Check it’s connected

Run MCP: List Servers from the Command Palette. mobster should be running, and Show Output there has its log. A workspace server inherits Workspace Trust; a server from another source shows a trust dialog the first time it starts. Then ask Copilot in agent mode:

```
Call mobster's status tool and tell me what it says.
```

## A first check: picking an answer

Say your app’s lesson asks the user to fill in a blank from three answers, and Check stays disabled until one is picked. A prompt that exercises a tap and a state change:

```
Build my app for the simulator and verify that tapping "café" on the lesson(yourapp://lesson) selects it and turns on the Check button.
```

Copilot calls `verify_start` with the absolute `app_path`, `open_url` set to `yourapp://lesson`, the step, and expectations it can’t meet before the tap, such as:

```
[{"visible": {"id": "answer_cafe", "selected": true}}, {"visible": {"id": "lesson_check", "enabled": true}}]
```

Then it reads the screen and taps by identifier:

```
{"tool": "tap", "arguments": {"run_id": "…", "target": {"id": "answer_cafe"}}}
```

That tap answers `Tapped “café”; the screen changed.`, and the new outline has `selected` on café. `verify_finish` then checks the expectation on a settled read and returns the verdict, the report path and the overlay frame. Writing an expectation that only holds after the steps matters: if it already held at launch, the run ends `needs_review`, because it wouldn’t show the tap did anything. [AI end-to-end tests for iOS](https://mobster.dev/blog/ai-e2e-tests-ios-assertions) explains that rule.

## Tell Copilot to verify every change

VS Code’s docs list `.github/copilot-instructions.md` or `AGENTS.md` as the project instruction files for the Copilot agent. Add:

```
## Verifying UI changesAfter you change a screen in this iOS app, verify it before you say it works.1. Build for the simulator:   xcodebuild -scheme <Scheme> -destination 'generic/platform=iOS Simulator' -derivedDataPath .mobster/build CODE_SIGNING_ALLOWED=NO build2. Call mobster's verify_start with app_path set to the absolute path of   .mobster/build/Build/Products/Debug-iphonesimulator/<App>.app, the steps in plain English, and expect:   what must be true when the steps are done.3. Drive with screen, tap, type_text and swipe, then call verify_finish.4. If the verdict is failed, fix the code and verify again. Report the verdict and the report path.
```

## Use a real iPhone

`list_devices` shows every device Mobster can use. With a USB iPhone’s name as `device` and no `run_id`, `screen`, `tap`, `type_text`, `swipe`, `alert`, `open_url`, `launch_app` and `home` drive the phone directly. Mobster holds the phone’s lock until `stop` with the `device`, or 90 idle seconds.

VS Code asks before a tool runs, and lets you approve a single use, the session, the workspace or every future call. “Chat: Manage Tool Approval” can trust every tool from one server. Be careful with both on a server that can reach your phone: an approval covers a tool, not a device, so trusting `tap` for simulator work trusts it on your iPhone. Keep the server to the phones you choose:

```
"args": ["mcp", "--allow-device", "Test iPhone"]
```

Mobster’s MCP annotations mark `status`, `screen`, `list_devices`, `wait`, `wait_for`, `read_notifications` and `unlock_status` as read-only and the rest as acting, and its instructions tell the agent to ask you before anything that sends, buys, posts or deletes on a real iPhone. A locked phone stops the call at once with “Your iPhone is locked. Unlock it and try again. No action was taken.”

## Troubleshooting

| Symptom | Fix |
|---|---|
| The server never appears | Check the top-level key: `servers` in `.vscode/mcp.json`, `mcpServers` in `.mcp.json` and `~/.copilot/mcp-config.json` |
| It appears but won’t start | Use the full path `/Applications/Mobster.app/Contents/MacOS/mobster-agent` in `command`, then restart it from MCP: List Servers |
| Copilot says too many tools are enabled | One request can use at most 128 tools. Turn off the tools or servers you don’t need for that chat |
| The first `verify_start` returns `status: "preparing"` | The simulator is booting and WebDriverAgent is building. Copilot calls `wait` |
| `couldnt_run` | `reason.class` and `reason.fix` in the result say what to do ([Checks](https://docs.mobster.dev/checks)) |

Every tool is in the [MCP reference](https://docs.mobster.dev/mcp-server).

## Questions

- ### Should Mobster go in .vscode/mcp.json or .mcp.json?
  Either works. VS Code's MCP: Add Server flow now prefers the portable .mcp.json at the workspace root, or ~/.copilot/mcp-config.json for your user, and labels .vscode/mcp.json deprecated. The two formats use different top-level keys, servers in .vscode/mcp.json and mcpServers in the portable files.
- ### Does Mobster fit under VS Code's tool limit?
  VS Code allows at most 128 tools in one chat request. Mobster's server offers about two dozen, so it fits beside other servers. If a chat hits the limit, turn off the tools you don't need for it.
- ### Where do I tell Copilot to verify UI changes?
  In .github/copilot-instructions.md or AGENTS.md, which VS Code's docs list as the project instruction files for the Copilot agent.

## Sources

We read each of these on 8 October 2026. Reviewed by Andy Guo on 8 October 2026. Corrections are welcome at the [GitHub repo](https://github.com/RadishSoftware/mobster/issues).

- [VS Code docs: add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
- [VS Code docs: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
- [VS Code docs: use tools in chat (128 tools per request)](https://code.visualstudio.com/docs/agents/run/tools)
- [VS Code docs: approvals and permissions](https://code.visualstudio.com/docs/agents/run/approvals)
- [VS Code docs: trust and safety](https://code.visualstudio.com/docs/agents/concepts/trust-and-safety)
- [VS Code docs: custom instructions](https://code.visualstudio.com/docs/agent-customization/custom-instructions)
- [MCP specification: ToolAnnotations (readOnlyHint)](https://modelcontextprotocol.io/specification/2025-11-25/schema)
- [Mobster docs: MCP server](https://docs.mobster.dev/mcp-server)
- [Mobster docs: checks](https://docs.mobster.dev/checks)
- [Mobster docs: device setup](https://docs.mobster.dev/device-setup)

VS Code’s logo is a trademark of Microsoft, shown only to name the product. Mobster isn’t affiliated with or endorsed by Microsoft.

## Read next

- [Every MCP tool, in the reference](https://docs.mobster.dev/mcp-server)
- [Getting started with verify](https://docs.mobster.dev/verify)

## Other agents

- [Claude Code](https://mobster.dev/connectors/claude-code)
- [Codex](https://mobster.dev/connectors/codex)
- [Cursor](https://mobster.dev/connectors/cursor)
- [Claude Desktop](https://mobster.dev/connectors/claude-desktop)
- [Gemini CLI](https://mobster.dev/connectors/gemini-cli)
- [opencode](https://mobster.dev/connectors/opencode)
- [Windsurf (Devin Desktop)](https://mobster.dev/connectors/windsurf)